@smarthome.exchange/integrations 1.0.0 → 3.0.0

package/ts/integrations/braviatv/braviatv.mapper.ts

@@ -1,147 +1,44 @@
-import * as plugins from '../../plugins.js';
+import type * as plugins from '../../plugins.js';
 import type { IIntegrationEntity } from '../../core/types.js';
-import type { IBraviatvSnapshot, IBraviatvState } from './braviatv.types.js';
+import type { IBraviatvSnapshot, TBraviatvControl } from './braviatv.types.js';
 
 export class BraviatvMapper {
-  public static toDevices(snapshotArg: IBraviatvSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
-    const state = this.state(snapshotArg);
-    const updatedAt = snapshotArg.updatedAt || new Date().toISOString();
-    return [{
-      id: this.deviceId(snapshotArg),
-      integrationDomain: 'braviatv',
-      name: this.deviceName(snapshotArg),
-      protocol: 'http',
-      manufacturer: 'Sony',
-      model: snapshotArg.systemInfo.model,
-      online: state.available !== false && state.power !== 'off',
-      features: [
-        { id: 'power', capability: 'media', name: 'Power', readable: true, writable: true },
-        { id: 'playback', capability: 'media', name: 'Playback', readable: true, writable: true },
-        { id: 'source', capability: 'media', name: 'Source', readable: true, writable: true },
-        { id: 'volume', capability: 'media', name: 'Volume', readable: true, writable: true, unit: '%' },
-        { id: 'muted', capability: 'media', name: 'Muted', readable: true, writable: true },
-        { id: 'remote_command', capability: 'media', name: 'Remote command', readable: false, writable: true },
-      ],
-      state: [
-        { featureId: 'power', value: state.power, updatedAt },
-        { featureId: 'playback', value: state.playback, updatedAt },
-        { featureId: 'source', value: this.source(snapshotArg) || null, updatedAt },
-        { featureId: 'volume', value: state.volumePercent ?? null, updatedAt },
-        { featureId: 'muted', value: state.muted ?? null, updatedAt },
-      ],
-      metadata: {
-        cid: snapshotArg.systemInfo.cid,
-        serialNumber: snapshotArg.systemInfo.serial,
-        macAddress: snapshotArg.systemInfo.macAddr,
-        generation: snapshotArg.systemInfo.generation,
-        sources: snapshotArg.sources.map((sourceArg) => ({ title: sourceArg.title, uri: sourceArg.uri, type: sourceArg.type })),
-        apps: snapshotArg.apps.map((appArg) => ({ title: appArg.title, uri: appArg.uri, icon: appArg.icon })),
-      },
-    }];
-  }
-
-  public static toEntities(snapshotArg: IBraviatvSnapshot): IIntegrationEntity[] {
-    const state = this.state(snapshotArg);
-    return [{
-      id: `media_player.${this.slug(this.deviceName(snapshotArg))}`,
-      uniqueId: `braviatv_${this.slug(this.identity(snapshotArg))}`,
-      integrationDomain: 'braviatv',
-      deviceId: this.deviceId(snapshotArg),
-      platform: 'media_player',
-      name: this.deviceName(snapshotArg),
-      state: this.mediaState(state),
-      attributes: {
-        source: this.source(snapshotArg),
-        sourceUri: state.sourceUri,
-        sourceList: this.sourceList(snapshotArg),
-        volumeLevel: state.volumeLevel,
-        isVolumeMuted: state.muted,
-        mediaTitle: state.mediaTitle,
-        mediaChannel: state.mediaChannel,
-        mediaContentId: state.mediaContentId,
-        mediaContentType: state.mediaContentType,
-        mediaDuration: state.mediaDuration,
-        mediaPosition: state.mediaPosition,
-        mediaPositionUpdatedAt: state.mediaPositionUpdatedAt,
-        model: snapshotArg.systemInfo.model,
-        powerStatus: state.powerStatus,
-      },
-      available: state.available !== false,
-    }];
-  }
-
-  public static deviceId(snapshotArg: IBraviatvSnapshot): string {
-    return `braviatv.device.${this.slug(this.identity(snapshotArg))}`;
-  }
-
-  private static state(snapshotArg: IBraviatvSnapshot): IBraviatvState & Required<Pick<IBraviatvState, 'power' | 'playback'>> {
-    const state = snapshotArg.state || {};
-    const power = state.power || this.powerFromStatus(state.powerStatus);
-    return {
-      ...state,
-      power,
-      playback: state.playback || (power === 'off' ? 'off' : 'idle'),
-      volumePercent: typeof state.volumePercent === 'number' ? state.volumePercent : typeof state.volumeLevel === 'number' ? Math.round(state.volumeLevel * 100) : undefined,
-    };
-  }
-
-  private static mediaState(stateArg: IBraviatvState): string {
-    if (stateArg.available === false) {
-      return 'unavailable';
-    }
-    if (stateArg.power === 'off') {
-      return 'off';
-    }
-    if (stateArg.playback === 'playing') {
-      return 'playing';
-    }
-    if (stateArg.playback === 'paused') {
-      return 'paused';
-    }
-    if (stateArg.power === 'unknown') {
-      return 'unknown';
-    }
-    return stateArg.source || stateArg.mediaTitle ? 'on' : 'idle';
-  }
-
-  private static source(snapshotArg: IBraviatvSnapshot): string | undefined {
-    return snapshotArg.state.source || this.sourceTitle(snapshotArg, snapshotArg.state.sourceUri) || snapshotArg.state.appTitle;
-  }
-
-  private static sourceList(snapshotArg: IBraviatvSnapshot): string[] {
-    const values = [...snapshotArg.sources, ...snapshotArg.apps, ...(snapshotArg.channels || [])]
-      .map((sourceArg) => sourceArg.title)
-      .filter(Boolean);
-    return [...new Set(values)];
-  }
-
-  private static sourceTitle(snapshotArg: IBraviatvSnapshot, uriArg: string | undefined): string | undefined {
-    if (!uriArg) {
-      return undefined;
-    }
-    return [...snapshotArg.sources, ...snapshotArg.apps, ...(snapshotArg.channels || [])].find((sourceArg) => sourceArg.uri === uriArg)?.title;
-  }
-
-  private static powerFromStatus(statusArg: string | undefined): 'on' | 'off' | 'unknown' {
-    const status = (statusArg || '').toLowerCase();
-    if (status === 'active') {
-      return 'on';
-    }
-    if (status === 'standby' || status === 'off') {
-      return 'off';
-    }
-    return 'unknown';
-  }
-
-  private static deviceName(snapshotArg: IBraviatvSnapshot): string {
-    return snapshotArg.systemInfo.name || snapshotArg.systemInfo.model || 'Sony Bravia TV';
-  }
-
-  private static identity(snapshotArg: IBraviatvSnapshot): string {
-    return snapshotArg.systemInfo.cid || snapshotArg.systemInfo.macAddr || snapshotArg.systemInfo.serial || this.deviceName(snapshotArg);
-  }
-
-  private static slug(valueArg: string): string {
-    return valueArg.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'braviatv';
+  public static deviceId(homeId: string, macAddress: string): string {
+    return `braviatv.display.${encodeURIComponent(homeId)}.${macAddress.replace(/:/g, '').toLowerCase()}`;
+  }
+  public static entityId(homeId: string, macAddress: string, feature: TBraviatvControl['feature']): string {
+    return `${feature === 'speaker_volume_raw' ? 'number' : 'switch'}.braviatv.${encodeURIComponent(homeId)}.${macAddress.replace(/:/g, '').toLowerCase()}.${feature}`;
+  }
+  public static toDevices(snapshot: IBraviatvSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
+    const features: plugins.shxInterfaces.data.IDeviceFeature[] = [];
+    const state: plugins.shxInterfaces.data.IDeviceState[] = [];
+    if (snapshot.power !== undefined) {
+      features.push({ id: 'power', capability: 'switch', name: 'Reported display power', readable: true, writable: snapshot.capabilities.power });
+      state.push({ featureId: 'power', value: snapshot.power, updatedAt: snapshot.observedAt });
+    }
+    if (snapshot.speaker) {
+      features.push({ id: 'device_mute', capability: 'switch', name: 'Device mute (speaker observation)', readable: true, writable: snapshot.capabilities.deviceMute },
+        { id: 'speaker_volume_raw', capability: 'sensor', name: 'Reported speaker volume', unit: 'raw level', readable: true, writable: snapshot.capabilities.speakerVolume });
+      state.push({ featureId: 'device_mute', value: snapshot.speaker.muted, updatedAt: snapshot.observedAt },
+        { featureId: 'speaker_volume_raw', value: snapshot.speaker.volumeRaw, updatedAt: snapshot.observedAt });
+    }
+    return [{ id: this.deviceId(snapshot.homeId, snapshot.identity.macAddress), integrationDomain: 'braviatv',
+      name: snapshot.name, protocol: 'http', manufacturer: 'Sony', model: snapshot.identity.model, online: true, features, state,
+      metadata: { homeId: snapshot.homeId, host: snapshot.host, port: snapshot.port, macAddress: snapshot.identity.macAddress,
+        serialNumber: snapshot.identity.serial, stateSource: 'independent-display-report', identityAuthentication: 'psk-does-not-prove-peer-identity',
+        unencryptedLan: true, volumeLimitRaw: snapshot.capabilities.volumeLimitRaw,
+        ...(snapshot.speaker ? { minimumVolumeRaw: snapshot.speaker.minimumVolumeRaw, maximumVolumeRaw: snapshot.speaker.maximumVolumeRaw } : {}) } }];
+  }
+  public static toEntities(snapshot: IBraviatvSnapshot): IIntegrationEntity[] {
+    const device = this.toDevices(snapshot)[0];
+    return device.features.map((feature) => ({
+      id: this.entityId(snapshot.homeId, snapshot.identity.macAddress, feature.id as TBraviatvControl['feature']),
+      uniqueId: `${device.id}.${feature.id}`, integrationDomain: 'braviatv', deviceId: device.id,
+      platform: feature.id === 'speaker_volume_raw' ? 'number' : 'switch', name: `${snapshot.name} ${feature.name}`,
+      state: device.state.find((entry) => entry.featureId === feature.id)!.value, available: true,
+      attributes: { ...device.metadata, observedAt: snapshot.observedAt, writable: feature.writable,
+        ...(feature.id === 'speaker_volume_raw' ? { step: 1, minimum: snapshot.speaker!.minimumVolumeRaw,
+          maximum: snapshot.speaker!.maximumVolumeRaw,
+          ...(snapshot.capabilities.speakerVolume ? { maximumWritableRaw: Math.min(snapshot.speaker!.maximumVolumeRaw, snapshot.capabilities.volumeLimitRaw) } : {}) } : {}) } }));
   }
 }

package/ts/integrations/braviatv/braviatv.types.ts

@@ -1,194 +1,74 @@
-export type TBraviatvPowerStatus = 'active' | 'standby' | 'off' | 'unknown' | string;
-
-export type TBraviatvPowerState = 'on' | 'off' | 'unknown';
-
-export type TBraviatvPlaybackState = 'playing' | 'paused' | 'idle' | 'off' | 'unknown';
-
-export type TBraviatvSourceType = 'input' | 'app' | 'channel';
-
-export type TBraviatvRestService = 'accessControl' | 'appControl' | 'audio' | 'avContent' | 'guide' | 'system' | 'video' | 'videoScreen';
+import type * as plugins from '../../plugins.js';
+import type { IIntegrationSetupContext } from '../../core/types.js';
 
+/** Selected BRAVIA Professional v1.0 endpoint; this object contains no credential. */
 export interface IBraviatvConfig {
-  host?: string;
-  port?: number;
-  useSsl?: boolean;
-  psk?: string;
-  pin?: string;
-  usePsk?: boolean;
-  clientId?: string;
-  nickname?: string;
+  homeId: string;
+  host: string;
+  expectedModel: string;
+  expectedMacAddress: string;
+  expectedSerial?: string;
+  credentialRef: string;
+  allowUnencryptedLan: true;
+  volumeLimitRaw: number;
   name?: string;
-  model?: string;
-  manufacturer?: string;
-  macAddress?: string;
-  serialNumber?: string;
-  cid?: string;
+  port?: number;
   timeoutMs?: number;
-  irccEndpoint?: 'ircc' | 'IRCC' | string;
-  fetchChannels?: boolean;
-  systemInfo?: IBraviatvSystemInfo;
-  state?: IBraviatvState;
-  sources?: IBraviatvSource[];
-  apps?: IBraviatvApp[];
-  channels?: IBraviatvChannel[];
-  commands?: Record<string, string>;
-  snapshot?: IBraviatvSnapshot;
-  scalarWebApiBaseUrl?: string;
+  maxPendingOperations?: number;
+  maxResponseBytes?: number;
 }
-
 export interface IHomeAssistantBraviatvConfig extends IBraviatvConfig {}
 
-export interface IBraviatvSystemInfo {
-  product?: string;
-  region?: string;
-  language?: string;
-  model?: string;
-  serial?: string;
-  macAddr?: string;
-  name?: string;
-  generation?: string;
-  area?: string;
-  cid?: string;
-  [key: string]: unknown;
-}
-
-export interface IBraviatvVolumeInfo {
-  target?: string;
-  volume?: number | string;
-  minVolume?: number;
-  maxVolume?: number;
-  mute?: boolean;
-  [key: string]: unknown;
-}
-
-export interface IBraviatvPlayingInfo {
-  title?: string;
-  uri?: string;
-  source?: string;
-  programTitle?: string;
-  dispNum?: string;
-  durationSec?: number;
-  startDateTime?: string;
-  mediaType?: string;
-  [key: string]: unknown;
-}
-
-export interface IBraviatvSource {
-  title: string;
-  uri: string;
-  type?: TBraviatvSourceType;
-  icon?: string;
-  label?: string;
-  connection?: string;
-  status?: string;
-  dispNum?: string;
-  [key: string]: unknown;
-}
-
-export interface IBraviatvApp extends IBraviatvSource {
-  type?: 'app';
-}
-
-export interface IBraviatvChannel extends IBraviatvSource {
-  type?: 'channel';
-  dispNum?: string;
-}
-
-export interface IBraviatvState {
-  powerStatus?: TBraviatvPowerStatus;
-  power?: TBraviatvPowerState;
-  playback?: TBraviatvPlaybackState;
-  available?: boolean;
-  source?: string;
-  sourceUri?: string;
-  appTitle?: string;
-  volumeLevel?: number;
-  volumePercent?: number;
-  muted?: boolean;
-  mediaTitle?: string;
-  mediaChannel?: string;
-  mediaContentId?: string;
-  mediaContentType?: string;
-  mediaDuration?: number;
-  mediaPosition?: number;
-  mediaPositionUpdatedAt?: string;
-  lastError?: string;
-}
-
-export interface IBraviatvSnapshot {
-  systemInfo: IBraviatvSystemInfo;
-  state: IBraviatvState;
-  sources: IBraviatvSource[];
-  apps: IBraviatvApp[];
-  channels?: IBraviatvChannel[];
-  commands?: Record<string, string>;
-  updatedAt?: string;
-}
-
-export interface IBraviatvRestCommand {
-  type: 'rest';
-  service: TBraviatvRestService;
-  method: string;
-  params?: unknown[];
-  version?: string;
-}
-
-export interface IBraviatvIrccCommand {
-  type: 'ircc';
-  command?: string;
-  code?: string;
-}
-
-export interface IBraviatvSourceCommand {
-  type: 'source';
-  source: string;
-}
-
-export type TBraviatvCommand = IBraviatvRestCommand | IBraviatvIrccCommand | IBraviatvSourceCommand;
-
-export interface IBraviatvEvent {
-  type: 'snapshot' | 'command' | 'error';
-  command?: TBraviatvCommand;
-  snapshot?: IBraviatvSnapshot;
-  message?: string;
-  timestamp: number;
-}
-
+export interface IBraviatvCredentialRequest {
+  readonly homeId: string;
+  readonly credentialRef: string;
+  readonly signal: AbortSignal;
+  readonly deadline: number;
+}
+/** Caller owns credential retrieval, storage and its cancellation implementation. */
+export type TBraviatvPskResolver = (request: IBraviatvCredentialRequest) => Promise<string>;
+export interface IBraviatvIntegrationOptions {
+  readonly homeId?: string;
+  readonly capacity?: number;
+  readonly resolvePsk: TBraviatvPskResolver;
+}
+export interface IBraviatvSetupContext extends IIntegrationSetupContext { homeId: string; }
+
+export interface IBraviatvSnapshot extends plugins.ecobridgeDeviceManager.ISonyBraviaState {
+  readonly homeId: string;
+  readonly host: string;
+  readonly port: number;
+  readonly name: string;
+}
+export interface IBraviatvEffectResult {
+  readonly control: plugins.ecobridgeDeviceManager.ISonyBraviaControlObservation['control'];
+  readonly requested: boolean | number;
+  readonly commandAcknowledged: true;
+  readonly causalityConfirmed: false;
+  readonly observation: plugins.ecobridgeDeviceManager.ISonyBraviaControlObservation['observation'];
+  readonly snapshot: IBraviatvSnapshot;
+}
+export type TBraviatvControl = { feature: 'power'; value: boolean }
+  | { feature: 'device_mute'; value: boolean }
+  | { feature: 'speaker_volume_raw'; value: number };
+
+/** Unverified discovery hints do not establish identity or authorize control. */
 export interface IBraviatvSsdpRecord {
-  st?: string;
-  usn?: string;
-  location?: string;
+  st?: string; usn?: string; location?: string;
   headers?: Record<string, string | undefined>;
   upnp?: Record<string, unknown>;
-  ssdp_st?: string;
-  ssdp_usn?: string;
-  ssdp_location?: string;
+  ssdp_st?: string; ssdp_usn?: string; ssdp_location?: string;
   [key: string]: unknown;
 }
-
 export interface IBraviatvMdnsRecord {
-  type?: string;
-  name?: string;
-  host?: string;
-  port?: number;
+  type?: string; name?: string; host?: string; port?: number;
   txt?: Record<string, string | undefined>;
   properties?: Record<string, string | undefined>;
   metadata?: Record<string, unknown>;
 }
-
 export interface IBraviatvManualEntry {
-  host?: string;
-  port?: number;
-  id?: string;
-  name?: string;
-  model?: string;
-  manufacturer?: string;
-  macAddress?: string;
-  serialNumber?: string;
-  cid?: string;
-  psk?: string;
-  useSsl?: boolean;
+  host?: string; port?: number; id?: string; name?: string; model?: string;
+  manufacturer?: string; macAddress?: string; serialNumber?: string; cid?: string;
   metadata?: Record<string, unknown>;
 }
-
 export type TBraviatvDiscoveryRecord = IBraviatvSsdpRecord | IBraviatvMdnsRecord | IBraviatvManualEntry;

package/ts/integrations/braviatv/braviatv.validation.ts

@@ -0,0 +1,68 @@
+import * as plugins from '../../plugins.js';
+import type { IBraviatvConfig, IBraviatvIntegrationOptions, TBraviatvControl } from './braviatv.types.js';
+
+export function braviatvRecord(value: unknown, allowed?: readonly string[]): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+    throw new TypeError('BRAVIA input must be a plain data object.');
+  }
+  const result: Record<string, unknown> = {};
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (typeof key !== 'string' || allowed && !allowed.includes(key) || !descriptor || !('value' in descriptor) || !descriptor.enumerable) {
+      throw new TypeError('BRAVIA input contains an unsupported field or accessor.');
+    }
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+}
+export function braviatvText(value: unknown, label: string, maximum = 128): string {
+  if (typeof value !== 'string' || !value || value !== value.trim() || value.length > maximum || /[\p{Cc}\p{Cs}]/u.test(value)) {
+    throw new TypeError(`BRAVIA ${label} must be bounded text without control characters.`);
+  }
+  return value;
+}
+export function braviatvInteger(value: unknown, minimum: number, maximum: number): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw new TypeError('BRAVIA integer is outside its supported bounds.');
+  }
+  return value;
+}
+export function normalizeBraviatvConfig(value: unknown): Readonly<Required<Omit<IBraviatvConfig, 'expectedSerial' | 'name'>> & Pick<IBraviatvConfig, 'expectedSerial' | 'name'>> {
+  const config = braviatvRecord(value, ['homeId', 'host', 'expectedModel', 'expectedMacAddress', 'expectedSerial',
+    'credentialRef', 'allowUnencryptedLan', 'volumeLimitRaw', 'name', 'port', 'timeoutMs', 'maxPendingOperations', 'maxResponseBytes']);
+  const host = braviatvText(config.host, 'selected IPv4', 15);
+  const [first, second, , last] = host.split('.').map(Number);
+  if (plugins.net.isIP(host) !== 4 || !(first === 10 || first === 127 || first === 172 && second >= 16 && second <= 31 || first === 192 && second === 168) || last === 0 || last === 255) {
+    throw new TypeError('BRAVIA requires a selected private or loopback host IPv4 address.');
+  }
+  const mac = braviatvText(config.expectedMacAddress, 'selected active-network MAC', 17);
+  if (!/^(?:[0-9a-f]{2}:){5}[0-9a-f]{2}$/i.test(mac) || /^(?:00:){5}00$|^(?:ff:){5}ff$/i.test(mac) || (Number.parseInt(mac.slice(0, 2), 16) & 1) !== 0) {
+    throw new TypeError('BRAVIA requires an exact usable active-network MAC.');
+  }
+  if (config.allowUnencryptedLan !== true) throw new TypeError('BRAVIA requires explicit unencrypted LAN consent.');
+  return Object.freeze({ homeId: braviatvText(config.homeId, 'home ID', 256), host,
+    expectedModel: braviatvText(config.expectedModel, 'selected model'), expectedMacAddress: mac.toUpperCase(),
+    ...(config.expectedSerial === undefined ? {} : { expectedSerial: braviatvText(config.expectedSerial, 'selected serial') }),
+    credentialRef: braviatvText(config.credentialRef, 'credential reference', 256), allowUnencryptedLan: true,
+    volumeLimitRaw: braviatvInteger(config.volumeLimitRaw, 0, 100),
+    ...(config.name === undefined ? {} : { name: braviatvText(config.name, 'display name') }),
+    port: braviatvInteger(config.port ?? 80, 1, 65535), timeoutMs: braviatvInteger(config.timeoutMs ?? 5000, 1, 30000),
+    maxPendingOperations: braviatvInteger(config.maxPendingOperations ?? 16, 1, 128),
+    maxResponseBytes: braviatvInteger(config.maxResponseBytes ?? 32768, 1024, 65536) });
+}
+export function normalizeBraviatvOptions(value: unknown): Readonly<IBraviatvIntegrationOptions> {
+  const options = braviatvRecord(value, ['homeId', 'capacity', 'resolvePsk']);
+  if (typeof options.resolvePsk !== 'function') throw new TypeError('BRAVIA requires a caller-owned PSK resolver.');
+  return Object.freeze({
+    ...(options.homeId === undefined ? {} : { homeId: braviatvText(options.homeId, 'caller home ID', 256) }),
+    ...(options.capacity === undefined ? {} : { capacity: braviatvInteger(options.capacity, 1, Number.MAX_SAFE_INTEGER) }),
+    resolvePsk: options.resolvePsk as IBraviatvIntegrationOptions['resolvePsk'],
+  });
+}
+export function validateBraviatvControl(value: unknown): TBraviatvControl {
+  const control = braviatvRecord(value, ['feature', 'value']);
+  if (control.feature === 'power' && typeof control.value === 'boolean') return { feature: 'power', value: control.value };
+  if (control.feature === 'device_mute' && typeof control.value === 'boolean') return { feature: 'device_mute', value: control.value };
+  if (control.feature === 'speaker_volume_raw') return { feature: 'speaker_volume_raw', value: braviatvInteger(control.value, 0, 100) };
+  throw new TypeError('BRAVIA supports absolute power, device mute and integer speaker volume only.');
+}

package/ts/integrations/broadlink/broadlink.actions.ts

@@ -0,0 +1,31 @@
+import * as plugins from '../../plugins.js';
+import { broadlinkRecord, broadlinkName } from './broadlink.validation.js';
+import type { IBroadlinkIrAction } from './broadlink.types.js';
+
+export const readBroadlinkActions = (valueArg: unknown): ReadonlyArray<Readonly<IBroadlinkIrAction>> => {
+  if (!Array.isArray(valueArg) || Object.getPrototypeOf(valueArg) !== Array.prototype
+    || valueArg.length < 1 || valueArg.length > 32 || Reflect.ownKeys(valueArg).length !== valueArg.length + 1) {
+    throw new TypeError('Broadlink requires 1 through 32 owner-configured IR actions in a dense array.');
+  }
+  const ids = new Set<string>();
+  const actions: Readonly<IBroadlinkIrAction>[] = [];
+  for (let index = 0; index < valueArg.length; index++) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, String(index));
+    if (!descriptor?.enumerable || !('value' in descriptor)) throw new TypeError('Broadlink actions may not contain accessors or holes.');
+    const action = broadlinkRecord(descriptor.value, ['id', 'name', 'packetBase64']);
+    if (typeof action.id !== 'string' || !/^[a-z][a-z0-9_-]{0,63}$/.test(action.id) || ids.has(action.id)) {
+      throw new TypeError('Broadlink action IDs must be unique lowercase identifiers, at most 64 characters.');
+    }
+    const name = broadlinkName(action.name, 'action name', 128);
+    if (typeof action.packetBase64 !== 'string' || action.packetBase64.length > 1368) throw new TypeError('Broadlink IR action requires bounded canonical base64.');
+    const packet = Buffer.from(action.packetBase64, 'base64');
+    try {
+      if (packet.toString('base64') !== action.packetBase64) throw new TypeError('Broadlink IR action requires canonical base64.');
+      const validated = plugins.ecobridgeDeviceManager.copyBroadlinkIrPacket(packet);
+      validated.fill(0);
+    } finally { packet.fill(0); }
+    ids.add(action.id);
+    actions.push(Object.freeze({ id: action.id, name, packetBase64: action.packetBase64 }));
+  }
+  return Object.freeze(actions);
+};