@smarthome.exchange/integrations 1.0.0 → 3.0.0

package/ts/integrations/kodi/kodi.types.ts

@@ -1,19 +1,42 @@
+import type * as plugins from '../../plugins.js';
+import type { INativeConfigFlowContext, INativeIntegrationSetupContext } from '../../core/types.js';
+
 export interface IKodiConfig {
-  host?: string;
-  port?: number;
-  wsPort?: number;
-  ssl?: boolean;
-  username?: string;
-  password?: string;
+  homeId: string;
+  origin: string;
+  expectedApplicationName: string;
+  expectedApplicationMajor: number;
+  /** Plain HTTP does not authenticate the selected server. */
+  allowUnencryptedHttp: true;
+  control?: { readonly trustSelectedEndpoint: true; readonly maximumVolume: number };
   timeoutMs?: number;
+  maxQueuedOperations?: number;
+  maxResponseBytes?: number;
   name?: string;
-  uniqueId?: string;
-  deviceInfo?: IKodiDeviceInfo;
-  snapshot?: IKodiSnapshot;
 }
 
 export interface IHomeAssistantKodiConfig extends IKodiConfig {}
 
+export interface IKodiClientOptions {
+  /** Caller-owned provider and secret storage; honor its cancellation signal. */
+  getBasicCredentials?: plugins.ecobridgeDeviceManager.IKodiProtocolOptions['getBasicCredentials'];
+}
+
+export interface IKodiIntegrationOptions extends Pick<IKodiClientOptions, 'getBasicCredentials'> {
+  homeId?: string;
+}
+
+/** Explicit selection by the embedding host; the string is not an authentication credential. */
+export interface IKodiSetupContext extends INativeIntegrationSetupContext {}
+
+export interface IKodiConfigFlowContext extends INativeConfigFlowContext {}
+
+export interface IKodiNativeSnapshot extends plugins.ecobridgeDeviceManager.IKodiSnapshot {
+  readonly homeId: string;
+  readonly name: string;
+  readonly online: true;
+}
+
 export interface IKodiDeviceInfo {
   id?: string;
   uuid?: string;
@@ -91,6 +114,7 @@ export interface IKodiMediaItem {
   [key: string]: unknown;
 }
 
+/** Pure imported data for offline conversion; never native runtime authority. */
 export interface IKodiSnapshot {
   deviceInfo: IKodiDeviceInfo;
   application?: IKodiApplicationProperties;
@@ -125,52 +149,3 @@ export interface IKodiManualEntry {
   manufacturer?: string;
   metadata?: Record<string, unknown>;
 }
-
-export type TKodiJsonRpcParams = Record<string, unknown> | unknown[] | undefined;
-
-export interface IKodiJsonRpcRequest {
-  jsonrpc: '2.0';
-  method: string;
-  params?: TKodiJsonRpcParams;
-  id: number;
-}
-
-export interface IKodiJsonRpcResponse<T = unknown> {
-  jsonrpc?: string;
-  result?: T;
-  error?: {
-    code?: number;
-    message?: string;
-    data?: unknown;
-  };
-  id?: number;
-}
-
-export type TKodiMediaType =
-  | 'album'
-  | 'artist'
-  | 'channel'
-  | 'directory'
-  | 'episode'
-  | 'file'
-  | 'movie'
-  | 'music'
-  | 'playlist'
-  | 'season'
-  | 'song'
-  | 'track'
-  | 'tvshow'
-  | 'url'
-  | 'video'
-  | string;
-
-export type TKodiInputCommand =
-  | 'up'
-  | 'down'
-  | 'left'
-  | 'right'
-  | 'select'
-  | 'back'
-  | 'home'
-  | 'info'
-  | string;

package/ts/integrations/kodi/kodi.validation.ts

@@ -0,0 +1,60 @@
+import type { IKodiConfig } from './kodi.types.js';
+
+export function kodiRecord(value: unknown, name: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw new TypeError(`Kodi ${name} 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' || !descriptor || !('value' in descriptor) || !descriptor.enumerable) throw new TypeError(`Kodi ${name} cannot contain accessors, symbols or hidden fields.`);
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+}
+
+export function kodiKeys(record: Record<string, unknown>, names: readonly string[]): void {
+  if (Object.keys(record).some((key) => !names.includes(key))) throw new TypeError('Kodi data contains unsupported fields.');
+}
+
+export function kodiText(value: unknown, name: string, maximum = 128): string {
+  if (typeof value !== 'string' || !value.trim() || value.length > maximum || /[\p{Cc}\p{Cs}]/u.test(value)) throw new TypeError(`Kodi ${name} must be nonempty bounded text without control characters.`);
+  return value;
+}
+
+export function kodiInteger(value: unknown, minimum: number, maximum: number, name: string): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum || value > maximum) throw new TypeError(`Kodi ${name} must be an integer from ${minimum} through ${maximum}.`);
+  return value;
+}
+
+export function kodiBoolean(value: unknown): boolean {
+  if (typeof value !== 'boolean') throw new TypeError('Kodi muted state requires an explicit boolean.');
+  return value;
+}
+
+/** Captures consumer data; the public foundation validates the selected origin. */
+export function normalizeKodiConfig(value: unknown): Readonly<IKodiConfig> {
+  const config = kodiRecord(value, 'configuration');
+  kodiKeys(config, ['homeId', 'origin', 'expectedApplicationName', 'expectedApplicationMajor', 'allowUnencryptedHttp', 'control', 'name', 'timeoutMs', 'maxQueuedOperations', 'maxResponseBytes']);
+  if (config.allowUnencryptedHttp !== true) throw new TypeError('Kodi requires explicit allowUnencryptedHttp: true acceptance.');
+  let control: IKodiConfig['control'];
+  if (config.control !== undefined) {
+    const value = kodiRecord(config.control, 'owner control policy');
+    kodiKeys(value, ['trustSelectedEndpoint', 'maximumVolume']);
+    if (value.trustSelectedEndpoint !== true) throw new TypeError('Kodi controls require explicit owner trust of the selected endpoint.');
+    control = Object.freeze({ trustSelectedEndpoint: true, maximumVolume: kodiInteger(value.maximumVolume, 0, 100, 'owner volume ceiling') });
+  }
+  return Object.freeze({
+    homeId: kodiText(config.homeId, 'home id', 256), origin: kodiText(config.origin, 'origin', 128),
+    expectedApplicationName: kodiText(config.expectedApplicationName, 'selected application name'),
+    expectedApplicationMajor: kodiInteger(config.expectedApplicationMajor, 0, 255, 'selected application major'),
+    allowUnencryptedHttp: true, control, name: config.name === undefined ? undefined : kodiText(config.name, 'display name'),
+    timeoutMs: kodiInteger(config.timeoutMs === undefined ? 5000 : config.timeoutMs, 1, 60000, 'deadline'),
+    maxQueuedOperations: kodiInteger(config.maxQueuedOperations === undefined ? 16 : config.maxQueuedOperations, 1, 128, 'operation capacity'),
+    maxResponseBytes: kodiInteger(config.maxResponseBytes === undefined ? 65536 : config.maxResponseBytes, 1024, 1048576, 'response bound'),
+  });
+}
+
+export function kodiSignal(value: unknown): AbortSignal | undefined {
+  if (value !== undefined && !(value instanceof AbortSignal)) throw new TypeError('Kodi cancellation requires an AbortSignal.');
+  return value;
+}