@digital-alchemy/hass 25.11.17-beta.0 → 25.11.27

package/src/helpers/fetch/service-list.mts

@@ -1,7 +1,9 @@
 import type { LiteralUnion } from "type-fest";
 
 import type { ALL_DOMAINS, PICK_ENTITY, TPlatformId } from "../../user.mts";
+import type { SupportedCountries } from "../countries.mts";
 import type { ColorMode } from "../features.mts";
+import type { SupportedLanguages } from "../languages.mts";
 
 export type EntityFilterSelector = {
   integration?: TPlatformId;
@@ -33,16 +35,23 @@ export type LegacyDeviceSelector = {
 export interface ServiceListSelector {
   action: null;
   addon: {
+    /** The name of the addon */
     name?: string;
+    /** The slug identifier of the addon */
     slug?: string;
   };
   area: {
+    /** Device filter selector(s) to filter areas by device */
     device?: DeviceFilterSelector | DeviceFilterSelector[];
+    /** Entity filter selector(s) to filter areas by entity */
     entity?: EntityFilterSelector | EntityFilterSelector[];
+    /** Whether multiple areas can be selected */
     multiple?: boolean;
   };
   attribute: {
+    /** The entity ID to get attributes from */
     entity_id?: PICK_ENTITY;
+    /** List of attribute names to hide from the selector */
     hide_attributes?: string[];
   };
   assist_pipeline: null;
@@ -50,82 +59,131 @@ export interface ServiceListSelector {
   boolean: null;
   color_rgb: null;
   color_temp: {
+    /** The unit of measurement for color temperature */
     unit?: "kelvin" | "mired";
+    /** Minimum color temperature value */
     min?: number;
+    /** Maximum color temperature value */
     max?: number;
+    /** Maximum color temperature in mireds */
     max_mireds?: number;
+    /** Minimum color temperature in mireds */
     min_mireds?: number;
   };
   condition: null;
   config_entry: {
+    /** The integration platform ID */
     integration: TPlatformId;
   };
   constant: {
+    /** Display label for the constant value */
     label?: string;
+    /** The constant value */
     value: string | number | boolean;
+    /** Translation key for the label */
     translation_key?: string;
   };
   conversation_agent: {
+    /** Language code for the conversation agent */
     language?: string;
   };
   country: {
-    countries?: string | string[];
+    /** Country code(s) to include in the selector */
+    countries?: SupportedCountries | SupportedCountries[];
+    /** Whether to disable sorting of countries */
     no_sort?: boolean;
   };
   date: null;
   datetime: null;
   device: LegacyDeviceSelector & {
+    /** Whether multiple devices can be selected */
     multiple?: boolean;
+    /** Device filter selector(s) to filter devices */
     filter?: DeviceFilterSelector | DeviceFilterSelector[];
+    /** Entity filter selector(s) to filter devices by their entities */
     entity?: EntityFilterSelector | EntityFilterSelector[];
   };
   duration: {
+    /** Whether to enable day selection in duration input */
     enable_day?: boolean;
+    /** Whether to enable millisecond precision in duration input */
     enable_millisecond?: boolean;
+    /** Whether to allow negative duration values */
     allow_negative?: boolean;
   };
   entity: LegacyEntitySelector & {
-    exclude_entities?: PICK_ENTITY | PICK_ENTITY[];
-    include_entities?: PICK_ENTITY | PICK_ENTITY[];
+    /** Whether multiple entities can be selected */
     multiple?: boolean;
+    /** Whether entities can be reordered */
     reorder?: boolean;
+    /** Entity filter selector(s) to filter entities */
     filter?: EntityFilterSelector | EntityFilterSelector[];
-  };
+  } & (
+      | {
+          /** Entity ID(s) to exclude from the selector */
+          exclude_entities?: PICK_ENTITY | PICK_ENTITY[];
+          include_entities?: never;
+        }
+      | {
+          /** Entity ID(s) to include in the selector */
+          include_entities?: PICK_ENTITY | PICK_ENTITY[];
+          exclude_entities?: never;
+        }
+    );
   file: {
+    /** MIME type(s) or file extension(s) to accept */
     accept: string;
   };
   floor: {
+    /** Entity filter selector(s) to filter floors by entity */
     entity?: EntityFilterSelector | EntityFilterSelector[];
+    /** Device filter selector(s) to filter floors by device */
     device?: DeviceFilterSelector | DeviceFilterSelector[];
+    /** Whether multiple floors can be selected */
     multiple?: boolean;
   };
   icon: {
+    /** Placeholder text for the icon selector */
     placeholder?: string;
   };
   label: {
+    /** Whether multiple labels can be selected */
     multiple?: boolean;
   };
   language: {
-    languages?: string | string[];
+    /** Language code(s) to include in the selector */
+    languages?: SupportedLanguages | SupportedLanguages[];
+    /** Whether to display native language names */
     native_name?: boolean;
+    /** Whether to disable sorting of languages */
     no_sort?: boolean;
   };
   location: {
+    /** Whether to include radius selection */
     radius?: boolean;
+    /** Icon to display for the location selector */
     icon?: string;
   };
   media: {
+    /** MIME type(s) or file extension(s) to accept */
     accept?: string | string[];
   };
   number: {
+    /** Minimum value allowed */
     min?: number;
+    /** Maximum value allowed */
     max?: number;
+    /** Input mode: "box" for text input or "slider" for slider control */
     mode?: "box" | "slider";
+    /** Translation key for the number field */
     translation_key?: string;
+    /** Step value for increment/decrement, or "any" for no step */
     step?: number | "any";
+    /** Unit of measurement to display */
     unit_of_measurement?: string;
   };
   object: {
+    /** Field definitions for the object structure */
     fields?: Record<
       string,
       {
@@ -134,38 +192,58 @@ export interface ServiceListSelector {
         label?: string;
       }
     >;
+    /** Whether multiple objects can be selected */
     multiple?: boolean;
+    /** Field name to use as the label for each object */
     label_field?: string;
+    /** Field name to use as the description for each object */
     description_field?: string;
+    /** Translation key for the object selector */
     translation_key?: string;
   };
   qr_code: {
+    /** Data to encode in the QR code */
     data: string;
+    /** Scale factor for the QR code size */
     scale?: number;
+    /** Error correction level: L (low), M (medium), Q (quartile), H (high) */
     error_correction_level?: "L" | "M" | "Q" | "H";
   };
   select: {
+    /** Available options for selection */
     options: (string | { label: string; value: string })[];
+    /** Whether multiple options can be selected */
     multiple?: boolean;
+    /** Whether custom values can be entered */
     custom_value?: boolean;
+    /** Display mode: "dropdown" or "list" */
     mode?: "dropdown" | "list";
+    /** Translation key for the select field */
     translation_key?: string;
+    /** Whether to sort the options */
     sort?: boolean;
   };
   state: {
+    /** Entity ID to get states from */
     entity_id?: PICK_ENTITY;
+    /** Whether multiple states can be selected */
     multiple?: boolean;
+    /** List of state values to hide from the selector */
     hide_states?: string[];
   };
   statistic: {
+    /** Whether multiple statistics can be selected */
     multiple?: boolean;
   };
   target: {
+    /** Entity filter selector(s) to filter targets by entity */
     entity?: EntityFilterSelector | EntityFilterSelector[];
+    /** Device filter selector(s) to filter targets by device */
     device?: DeviceFilterSelector | DeviceFilterSelector[];
   };
   template: null;
   text: {
+    /** HTML input type for the text field */
     type?:
       | "color"
       | "date"
@@ -180,13 +258,19 @@ export interface ServiceListSelector {
       | "time"
       | "url"
       | "week";
+    /** Autocomplete attribute value */
     autocomplete?: string;
+    /** Whether the text input should be multiline */
     multiline?: boolean;
+    /** Prefix text to display before the input */
     prefix?: string;
+    /** Suffix text to display after the input */
     suffix?: string;
+    /** Whether multiple text values can be entered */
     multiple?: boolean;
   };
   theme: {
+    /** Whether to include default themes in the selector */
     include_defaults?: boolean;
   };
   time: null;

package/src/helpers/id-by.mts

@@ -47,5 +47,6 @@ export type IDByInterface = {
     >,
   >(
     unique_id: UNIQUE_ID,
+    platform?: TPlatformId,
   ) => ENTITY_ID;
 };

package/src/helpers/interfaces.mts

@@ -1,5 +1,6 @@
+import type EventEmitter from "node:events";
+
 import type { RemoveCallback, TBlackHole } from "@digital-alchemy/core";
-import type EventEmitter from "events";
 import type { EmptyObject } from "type-fest";
 import type WS from "ws";
 

package/src/mock_assistant/main.mts

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { cwd } from "node:process";
+
 import type { TServiceParams } from "@digital-alchemy/core";
 import { CreateApplication } from "@digital-alchemy/core";
-import { writeFileSync } from "fs";
-import { join } from "path";
-import { cwd } from "process";
 
 import { LIB_HASS } from "../index.mts";
 import type { ScannerCacheData } from "./helpers/index.mts";

package/src/mock_assistant/mock-assistant.module.mts

@@ -1,6 +1,7 @@
+import { join } from "node:path";
+import { cwd } from "node:process";
+
 import { CreateLibrary, createModule, SINGLE } from "@digital-alchemy/core";
-import { join } from "path";
-import { cwd } from "process";
 
 import { LIB_HASS } from "../hass.module.mts";
 import {

package/src/mock_assistant/services/fixtures.service.mts

@@ -1,6 +1,7 @@
+import { existsSync, readFileSync } from "node:fs";
+
 import type { TServiceParams } from "@digital-alchemy/core";
 import { BootstrapException } from "@digital-alchemy/core";
-import { existsSync, readFileSync } from "fs";
 
 import type { ENTITY_STATE } from "../../index.mts";
 import type { ANY_ENTITY } from "../../user.mts";

package/src/mock_assistant/services/websocket-api.service.mts

@@ -1,6 +1,7 @@
+import EventEmitter from "node:events";
+
 import type { TBlackHole, TServiceParams } from "@digital-alchemy/core";
 import { START } from "@digital-alchemy/core";
-import EventEmitter from "events";
 import type { PartialDeep, WritableDeep } from "type-fest";
 import type WS from "ws";
 

package/src/services/config.service.mts

@@ -1,7 +1,8 @@
 /* eslint-disable @typescript-eslint/no-magic-numbers */
+import { env } from "node:process";
+
 import type { TServiceParams } from "@digital-alchemy/core";
 import { asyncNoop, debounce, INCREMENT, SECOND, sleep, START } from "@digital-alchemy/core";
-import { env } from "process";
 
 import type {
   ALL_SERVICE_DOMAINS,

package/src/services/diagnostics.service.mts

@@ -1,5 +1,6 @@
+import { channel } from "node:diagnostics_channel";
+
 import type { TServiceParams } from "@digital-alchemy/core";
-import { channel } from "diagnostics_channel";
 
 function createDiagnostics<CHANNEL extends string>(context: string, channels: CHANNEL[]) {
   return Object.fromEntries(channels.map(i => [i, channel(`hass:${context}:${i}`)])) as Record<

package/src/services/id-by.service.mts

@@ -64,11 +64,14 @@ export function IDByExtension({
       HassUniqueIdMapping[UNIQUE_ID],
       ANY_ENTITY
     >,
-  >(unique_id: UNIQUE_ID): ENTITY_ID {
+  >(unique_id: UNIQUE_ID, platform?: TPlatformId): ENTITY_ID {
     hass.entity.warnEarly("byUniqueId");
     let list = hass.entity.registry.current.filter(
       i => i.unique_id === unique_id,
     ) as EntityRegistryItem<ENTITY_ID>[];
+    if (!is.empty(platform)) {
+      list = list.filter(i => i.platform === platform);
+    }
     if (is.empty(list)) {
       logger.error({ name: unique_id, unique_id }, `could not find an entity`);
       return undefined;

package/src/services/internal.service.mts

@@ -1,8 +1,9 @@
+import { createWriteStream } from "node:fs";
+import { pipeline } from "node:stream";
+import { promisify } from "node:util";
+
 import type { TServiceParams } from "@digital-alchemy/core";
 import { FIRST, InternalError } from "@digital-alchemy/core";
-import { createWriteStream } from "fs";
-import { pipeline } from "stream";
-import { promisify } from "util";
 
 import type {
   DownloadOptions,

package/src/services/reference.service.mts

@@ -136,7 +136,9 @@ export function ReferenceService({
         "attributes",
         "entity_id",
         "history",
-        "last",
+        "last_changed",
+        "last_reported",
+        "last_updated",
         "nextState",
         "once",
         "onStateFor",
@@ -357,7 +359,6 @@ export function ReferenceService({
             return async (state: string | number, timeout?: TOffset) =>
               await new Promise<ENTITY_STATE<ENTITY_ID>>(async done => {
                 const remove = () => {
-                  done = undefined;
                   listeners.delete(remove);
                   done = undefined;
                   logger.trace({ entity_id }, "remove [waitForState] listener");

package/src/services/websocket-api.service.mts

@@ -1,8 +1,9 @@
+import EventEmitter from "node:events";
+
 import type { TBlackHole, TServiceParams } from "@digital-alchemy/core";
 import { INCREMENT, InternalError, NONE, SECOND, sleep, START } from "@digital-alchemy/core";
 import type { Dayjs } from "dayjs";
 import dayjs from "dayjs";
-import EventEmitter from "events";
 import type { EmptyObject } from "type-fest";
 import WS from "ws";
 

package/src/testing/area.spec.mts

@@ -1,10 +1,11 @@
+import { subscribe } from "node:diagnostics_channel";
+
 import { sleep } from "@digital-alchemy/core";
-import { subscribe } from "diagnostics_channel";
 
 import type { AreaDetails } from "../helpers/index.mts";
-import { AREA_REGISTRY_UPDATED } from "../helpers/index.mts";
+import { AREA_REGISTRY_UPDATED, ENTITY_REGISTRY_UPDATED } from "../helpers/index.mts";
 import { hassTestRunner, INTERNAL_MESSAGE } from "../mock_assistant/index.mts";
-import type { TAreaId } from "../user.mts";
+import type { ANY_ENTITY, TAreaId } from "../user.mts";
 
 const EXAMPLE_AREA = {
   area_id: "empty_area" as TAreaId,
@@ -200,4 +201,168 @@ describe("API", () => {
       });
     });
   });
+
+  describe("apply", () => {
+    it("should apply area to a single entity", async () => {
+      expect.assertions(2);
+      await hassTestRunner.run(({ lifecycle, hass, event }) => {
+        const spy = vi.spyOn(hass.socket, "sendMessage").mockImplementation(async () => undefined);
+        lifecycle.onReady(async () => {
+          const entity = "sensor.magic" as ANY_ENTITY;
+          const area = "living_room" as TAreaId;
+          const response = hass.area.apply(area, [entity]);
+          setImmediate(() => event.emit(ENTITY_REGISTRY_UPDATED));
+          const result = await response;
+
+          expect(spy).toHaveBeenCalledWith({
+            area_id: area,
+            entity_id: entity,
+            type: "config/entity_registry/update",
+          });
+          expect(result.updated).toEqual([entity]);
+        });
+      });
+    });
+
+    it("should apply area to multiple entities", async () => {
+      expect.assertions(3);
+      await hassTestRunner.run(({ lifecycle, hass, event }) => {
+        lifecycle.onReady(async () => {
+          const updateCalls: Array<{ area_id: TAreaId; entity_id: ANY_ENTITY; type: string }> = [];
+          vi.spyOn(hass.socket, "sendMessage").mockImplementation(async message => {
+            if (message?.type === "config/entity_registry/update") {
+              updateCalls.push(
+                message as { area_id: TAreaId; entity_id: ANY_ENTITY; type: string },
+              );
+              // Emit event asynchronously to ensure listener is registered
+              setImmediate(() => event.emit(ENTITY_REGISTRY_UPDATED));
+            }
+            return undefined;
+          });
+
+          const entities = ["sensor.magic", "light.kitchen_lamp"] as ANY_ENTITY[];
+          const area = "living_room" as TAreaId;
+          const result = await hass.area.apply(area, entities);
+
+          expect(updateCalls).toHaveLength(2);
+          expect(updateCalls).toEqual([
+            {
+              area_id: area,
+              entity_id: entities[0],
+              type: "config/entity_registry/update",
+            },
+            {
+              area_id: area,
+              entity_id: entities[1],
+              type: "config/entity_registry/update",
+            },
+          ]);
+          expect(result.updated).toEqual(entities);
+        });
+      });
+    });
+
+    it("should skip entities that already have the correct area", async () => {
+      expect.assertions(2);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          const spy = vi
+            .spyOn(hass.socket, "sendMessage")
+            .mockImplementation(async () => undefined);
+          // Find an entity that already has an area assigned
+          const entityWithArea = hass.entity.registry.current.find(item => item.area_id !== null);
+          if (!entityWithArea) {
+            throw new Error("No entity with area found in fixtures");
+          }
+
+          const entity = entityWithArea.entity_id as ANY_ENTITY;
+          const area = entityWithArea.area_id as TAreaId;
+          const result = await hass.area.apply(area, [entity]);
+
+          const updateCalls = spy.mock.calls.filter(
+            call => call[0]?.type === "config/entity_registry/update",
+          );
+          expect(updateCalls).toHaveLength(0);
+          expect(result.updated).toEqual([]);
+        });
+      });
+    });
+
+    it("should throw error for unknown entity", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          const unknownEntity = "sensor.unknown_entity" as ANY_ENTITY;
+          const area = "living_room" as TAreaId;
+
+          try {
+            await hass.area.apply(area, [unknownEntity]);
+          } catch (error) {
+            // InternalError structure: check various possible properties
+            const err = error as Record<string, unknown>;
+            const errorString = String(error);
+            const hasCode = err.code === "UNKNOWN_ENTITY";
+            const hasName = err.name === "UNKNOWN_ENTITY";
+            const hasMessage = String(err.message || "").includes("UNKNOWN_ENTITY");
+            const hasString = errorString.includes("UNKNOWN_ENTITY");
+            expect(hasCode || hasName || hasMessage || hasString).toBe(true);
+          }
+        });
+      });
+    });
+
+    it("should wait for ENTITY_REGISTRY_UPDATED before continuing", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass, event }) => {
+        vi.spyOn(hass.socket, "sendMessage").mockImplementation(async () => undefined);
+        lifecycle.onReady(async () => {
+          const entity = "sensor.magic" as ANY_ENTITY;
+          const area = "living_room" as TAreaId;
+          const response = hass.area.apply(area, [entity]);
+          let order = "";
+          setTimeout(() => {
+            order += "a";
+            event.emit(ENTITY_REGISTRY_UPDATED);
+          }, 5);
+          await response;
+          order += "b";
+          expect(order).toEqual("ab");
+        });
+      });
+    });
+
+    it("should return only updated entities when some are skipped", async () => {
+      expect.assertions(2);
+      await hassTestRunner.run(({ lifecycle, hass, event }) => {
+        lifecycle.onReady(async () => {
+          const spy = vi.spyOn(hass.socket, "sendMessage").mockImplementation(async message => {
+            if (message?.type === "config/entity_registry/update") {
+              setImmediate(() => event.emit(ENTITY_REGISTRY_UPDATED));
+            }
+            return undefined;
+          });
+
+          // Find an entity that already has "kitchen" area so it will be skipped
+          const entityWithArea = hass.entity.registry.current.find(
+            item => item.area_id === "kitchen",
+          );
+          if (!entityWithArea) {
+            throw new Error("No entity with kitchen area found in fixtures");
+          }
+
+          const existingEntity = entityWithArea.entity_id as ANY_ENTITY;
+          const newEntity = "sensor.magic" as ANY_ENTITY;
+          const newArea = "kitchen" as TAreaId;
+
+          const result = await hass.area.apply(newArea, [existingEntity, newEntity]);
+
+          const updateCalls = spy.mock.calls.filter(
+            call => call[0]?.type === "config/entity_registry/update",
+          );
+          expect(updateCalls).toHaveLength(1);
+          expect(result.updated).toEqual([newEntity]);
+        });
+      });
+    });
+  });
 });