@digital-alchemy/hass 25.10.25 → 25.10.26

package/src/helpers/supported-features.mts

@@ -0,0 +1,328 @@
+/* eslint-disable sort-keys-fix/sort-keys-fix */
+
+import type { ALL_DOMAINS } from "../user.mts";
+
+/**
+ * homeassistant/components/light/const.py
+ */
+export const LIGHT = {
+  EFFECT: 4,
+  FLASH: 8,
+  TRANSITION: 32,
+} as const;
+
+/**
+ * homeassistant/components/vacuum/__init__.py
+ */
+export const VACUUM = {
+  /**
+   * Deprecated
+   */
+  TURN_ON: 1,
+  /**
+   * Deprecated
+   */
+  TURN_OFF: 2,
+  PAUSE: 4,
+  STOP: 8,
+  RETURN_HOME: 16,
+  FAN_SPEED: 32,
+  BATTERY: 64,
+  /**
+   * Deprecated
+   */
+  STATUS: 128,
+  SEND_COMMAND: 256,
+  LOCATE: 512,
+  CLEAN_SPOT: 1024,
+  MAP: 2048,
+  STATE: 4096,
+  START: 8192,
+} as const;
+
+/**
+ * homeassistant/components/water_heater/__init__.py
+ */
+export const WATER_HEATER = {
+  TARGET_TEMPERATURE: 1,
+  OPERATION_MODE: 2,
+  AWAY_MODE: 4,
+  ON_OFF: 8,
+} as const;
+
+/**
+ * homeassistant/components/valve/__init__.py
+ */
+export const VALVE = {
+  OPEN: 1,
+  CLOSE: 2,
+  SET_POSITION: 4,
+  STOP: 8,
+} as const;
+
+/**
+ * homeassistant/components/weather/const.py
+ */
+export const WEATHER = {
+  FORECAST_DAILY: 1,
+  FORECAST_HOURLY: 2,
+  FORECAST_TWICE_DAILY: 4,
+} as const;
+
+/**
+ * homeassistant/components/ai_task/const.py
+ */
+export const AI_TASK = {
+  ATTACHMENTS: 2,
+} as const;
+
+/**
+ * homeassistant/components/switch/__init__.py
+ */
+export const SWITCH = {
+  TURN_ON: 1,
+  TURN_OFF: 2,
+} as const;
+
+/**
+ * homeassistant/components/cover/__init__.py
+ */
+export const COVER = {
+  OPEN: 1,
+  CLOSE: 2,
+  SET_POSITION: 4,
+  STOP: 8,
+  OPEN_TILT: 16,
+  CLOSE_TILT: 32,
+  STOP_TILT: 64,
+  SET_TILT_POSITION: 128,
+} as const;
+
+/**
+ * homeassistant/components/fan/__init__.py
+ */
+export const FAN = {
+  SET_SPEED: 1,
+  OSCILLATE: 2,
+  DIRECTION: 4,
+  PRESET_MODE: 8,
+  TURN_OFF: 16,
+  TURN_ON: 32,
+} as const;
+
+/**
+ * homeassistant/components/climate/const.py
+ */
+export const CLIMATE = {
+  TARGET_TEMPERATURE: 1,
+  TARGET_TEMPERATURE_RANGE: 2,
+  TARGET_HUMIDITY: 4,
+  FAN_MODE: 8,
+  PRESET_MODE: 16,
+  SWING_MODE: 32,
+  TURN_OFF: 128,
+  TURN_ON: 256,
+  SWING_HORIZONTAL_MODE: 512,
+} as const;
+
+/**
+ * homeassistant/components/media_player/const.py
+ */
+export const MEDIA_PLAYER = {
+  PAUSE: 1,
+  SEEK: 2,
+  VOLUME_SET: 4,
+  VOLUME_MUTE: 8,
+  PREVIOUS_TRACK: 16,
+  NEXT_TRACK: 32,
+  TURN_ON: 128,
+  TURN_OFF: 256,
+  PLAY_MEDIA: 512,
+  VOLUME_STEP: 1024,
+  SELECT_SOURCE: 2048,
+  STOP: 4096,
+  CLEAR_PLAYLIST: 8192,
+  PLAY: 16384,
+  SHUFFLE_SET: 32768,
+  SELECT_SOUND_MODE: 65536,
+  BROWSE_MEDIA: 131072,
+  REPEAT_SET: 262144,
+  GROUPING: 524288,
+  MEDIA_ANNOUNCE: 1048576,
+  MEDIA_ENQUEUE: 2097152,
+  SEARCH_MEDIA: 4194304,
+} as const;
+
+/**
+ * homeassistant/components/camera/__init__.py
+ */
+export const CAMERA = {
+  ON_OFF: 1,
+  STREAM: 2,
+} as const;
+
+/**
+ * homeassistant/components/lock/__init__.py
+ */
+export const LOCK = {
+  OPEN: 1,
+} as const;
+
+/**
+ * homeassistant/components/alarm_control_panel/__init__.py
+ */
+export const ALARM_CONTROL_PANEL = {
+  ARM_HOME: 1,
+  ARM_AWAY: 2,
+  ARM_NIGHT: 4,
+  ARM_VACATION: 8,
+  ARM_CUSTOM_BYPASS: 16,
+} as const;
+
+/**
+ * homeassistant/components/binary_sensor/__init__.py
+ */
+export const BINARY_SENSOR = {
+  TURN_ON: 1,
+  TURN_OFF: 2,
+} as const;
+
+/**
+ * homeassistant/components/sensor/__init__.py
+ */
+export const SENSOR = {
+  TURN_ON: 1,
+  TURN_OFF: 2,
+} as const;
+
+/**
+ * homeassistant/components/update/const.py
+ */
+export const UPDATE = {
+  INSTALL: 1,
+  SPECIFIC_VERSION: 2,
+  PROGRESS: 4,
+  BACKUP: 8,
+  RELEASE_NOTES: 16,
+} as const;
+
+/**
+ * homeassistant/components/button/__init__.py
+ */
+export const BUTTON = {
+  TURN_ON: 1,
+  TURN_OFF: 2,
+} as const;
+
+/**
+ * homeassistant/components/number/__init__.py
+ */
+export const NUMBER = {
+  TURN_ON: 1,
+  TURN_OFF: 2,
+} as const;
+
+/**
+ * homeassistant/components/select/__init__.py
+ */
+export const SELECT = {
+  TURN_ON: 1,
+  TURN_OFF: 2,
+} as const;
+
+/**
+ * homeassistant/components/siren/const.py
+ */
+export const SIREN = {
+  TURN_ON: 1,
+  TURN_OFF: 2,
+  TONES: 4,
+  VOLUME_SET: 8,
+  DURATION: 16,
+} as const;
+
+/**
+ * homeassistant/components/text/__init__.py
+ */
+export const TEXT = {
+  TURN_ON: 1,
+  TURN_OFF: 2,
+} as const;
+
+/**
+ * homeassistant/components/todo/const.py
+ */
+export const TODO = {
+  CREATE_TODO_ITEM: 1,
+  DELETE_TODO_ITEM: 2,
+  UPDATE_TODO_ITEM: 4,
+  MOVE_TODO_ITEM: 8,
+  SET_DUE_DATE_ON_ITEM: 16,
+  SET_DUE_DATETIME_ON_ITEM: 32,
+  SET_DESCRIPTION_ON_ITEM: 64,
+} as const;
+
+/**
+ * homeassistant/components/humidifier/const.py
+ */
+export const HUMIDIFIER = {
+  MODES: 1,
+} as const;
+
+/**
+ * homeassistant/components/remote/__init__.py
+ */
+export const REMOTE = {
+  LEARN_COMMAND: 1,
+  DELETE_COMMAND: 2,
+  ACTIVITY: 4,
+} as const;
+
+/**
+ * homeassistant/components/notify/__init__.py
+ */
+export const NOTIFY = {
+  TITLE: 1,
+} as const;
+
+/**
+ * Registry for other library logic to take advantage of
+ */
+export const SUPPORTED_FEATURES = {
+  AI_TASK,
+  ALARM_CONTROL_PANEL,
+  BINARY_SENSOR,
+  BUTTON,
+  CAMERA,
+  CLIMATE,
+  COVER,
+  FAN,
+  HUMIDIFIER,
+  LIGHT,
+  LOCK,
+  MEDIA_PLAYER,
+  NOTIFY,
+  NUMBER,
+  REMOTE,
+  SELECT,
+  SENSOR,
+  SIREN,
+  SWITCH,
+  TEXT,
+  TODO,
+  UPDATE,
+  VACUUM,
+  VALVE,
+  WATER_HEATER,
+  WEATHER,
+} as const;
+
+export type SUPPORTED_FEATURES = typeof SUPPORTED_FEATURES;
+export type SupportedFeatureDomains = Extract<keyof SUPPORTED_FEATURES, string>;
+export type UsedSupportedFeatureDomains = Extract<Lowercase<SupportedFeatureDomains>, ALL_DOMAINS>;
+
+export type SupportedFeatures<DOMAIN extends SupportedFeatureDomains = SupportedFeatureDomains> =
+  `${DOMAIN}.${Extract<keyof SUPPORTED_FEATURES[DOMAIN], string>}`;
+export type SupportedEntityFeatures<
+  DOMAIN extends UsedSupportedFeatureDomains = UsedSupportedFeatureDomains,
+> = `${Uppercase<DOMAIN>}.${Extract<keyof SUPPORTED_FEATURES[Uppercase<DOMAIN>], string>}`;

package/src/services/feature.service.mts

@@ -0,0 +1,127 @@
+/* eslint-disable @typescript-eslint/no-magic-numbers */
+import { LABEL, type TServiceParams } from "@digital-alchemy/core";
+
+import type { ByIdProxy } from "../helpers/entity-state.mts";
+import type {
+  SupportedEntityFeatures,
+  SupportedFeatureDomains,
+  UsedSupportedFeatureDomains,
+} from "../index.mts";
+import { domain, SUPPORTED_FEATURES } from "../index.mts";
+import type { PICK_ENTITY } from "../user.mts";
+
+export function HassFeatureService({
+  hass,
+  logger,
+  internal: {
+    utils: { is },
+  },
+}: TServiceParams) {
+  /**
+   * Helper function to create supported features from an array of feature numbers
+   */
+  function createSupportedFeatures<T extends UsedSupportedFeatureDomains>(
+    features: (number | SupportedEntityFeatures<T>)[],
+  ): number {
+    return features.reduce((acc: number, feature) => {
+      if (is.string(feature)) {
+        const original = feature;
+        const [domain, featureName] = feature.split(".") as [SupportedFeatureDomains, string];
+        const featureDomain = SUPPORTED_FEATURES[domain] as Record<string, number>;
+        feature = featureDomain?.[featureName];
+        if (!featureDomain?.[featureName]) {
+          feature = 0;
+          logger.error({ feature: original }, `invalid feature lookup`);
+        }
+      }
+      return acc | feature;
+    }, 0);
+  }
+
+  function lookup(input: PICK_ENTITY | ByIdProxy<PICK_ENTITY>) {
+    const ref = is.string(input) ? hass.refBy.id(input) : input;
+    const attributes = ref.attributes as { supported_features: number };
+    return attributes?.supported_features ?? 0;
+  }
+
+  /**
+   *  Helper function to check if an entity supports a specific feature
+   */
+  function hasFeature<T extends UsedSupportedFeatureDomains>(
+    input: number | PICK_ENTITY<T> | ByIdProxy<PICK_ENTITY<T>>,
+    feature: number | SupportedEntityFeatures<T>,
+  ): boolean {
+    const features = is.number(input) ? input : lookup(input);
+    if (is.string(feature)) {
+      const original = feature;
+      const [domain, featureName] = feature.split(".") as [SupportedFeatureDomains, string];
+      const featureDomain = SUPPORTED_FEATURES[domain] as Record<string, number>;
+      feature = featureDomain?.[featureName];
+      if (!feature) {
+        feature = 0;
+        logger.error({ feature: original }, `invalid feature lookup`);
+      }
+    }
+    return (features & feature) !== 0;
+  }
+
+  /**
+   * Helper function to get all supported features as an array
+   * Can accept a number (bitmask), entity ID, or entity proxy
+   */
+  function getSupportedFeatures(input: number | PICK_ENTITY | ByIdProxy<PICK_ENTITY>): number[] {
+    const features = is.number(input) ? input : lookup(input);
+
+    const supported: number[] = [];
+    let bit = 1;
+    while (bit <= features) {
+      if ((features & bit) !== 0) {
+        supported.push(bit);
+      }
+      bit <<= 1;
+    }
+    return supported;
+  }
+
+  function listEntityFeatures<
+    DOMAIN extends UsedSupportedFeatureDomains = UsedSupportedFeatureDomains,
+  >(
+    input: PICK_ENTITY<DOMAIN> | ByIdProxy<PICK_ENTITY<DOMAIN>>,
+  ): SupportedEntityFeatures<DOMAIN>[] {
+    const inputDomain = domain(is.string(input) ? input : input.entity_id);
+    const domainFeatures = SUPPORTED_FEATURES[inputDomain.toUpperCase() as SupportedFeatureDomains];
+    if (!domainFeatures) {
+      return [];
+    }
+    const features = lookup(input);
+
+    const supported: number[] = [];
+    let bit = 1;
+    while (bit <= features) {
+      if ((features & bit) !== 0) {
+        supported.push(bit);
+      }
+      bit <<= 1;
+    }
+
+    const options = Object.entries(domainFeatures);
+    return supported
+      .map(i => {
+        const found = options.find(([, value]) => value === i);
+        if (!found) return null;
+        return (inputDomain.toUpperCase() +
+          "." +
+          found[
+            LABEL
+          ]) as `${Uppercase<DOMAIN>}.${Extract<keyof SUPPORTED_FEATURES[Uppercase<DOMAIN>], string>}`;
+      })
+      .filter(Boolean);
+  }
+
+  return {
+    createSupportedFeatures,
+    getSupportedFeatures,
+    hasFeature,
+    listEntityFeatures,
+  };
+}

package/src/services/index.mts

@@ -6,6 +6,7 @@ export * from "./device.service.mts";
 export * from "./diagnostics.service.mts";
 export * from "./entity.service.mts";
 export * from "./events.service.mts";
+export * from "./feature.service.mts";
 export * from "./fetch-api.service.mts";
 export * from "./floor.service.mts";
 export * from "./id-by.service.mts";

package/src/testing/feature.spec.mts

@@ -0,0 +1,219 @@
+import { LIGHT } from "../helpers/supported-features.mts";
+import { hassTestRunner } from "../mock_assistant/index.mts";
+
+afterEach(async () => {
+  await hassTestRunner.teardown();
+  vi.restoreAllMocks();
+});
+
+describe("Feature Service", () => {
+  describe("createSupportedFeatures", () => {
+    it("should create bitmask from array of numbers", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          const result = hass.feature.createSupportedFeatures([LIGHT.EFFECT, LIGHT.FLASH]);
+          expect(result).toBe(LIGHT.EFFECT | LIGHT.FLASH);
+        });
+      });
+    });
+
+    it("should create bitmask from array of feature strings", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          const result = hass.feature.createSupportedFeatures<"light">([
+            "LIGHT.EFFECT",
+            "LIGHT.FLASH",
+          ]);
+          expect(result).toBe(LIGHT.EFFECT | LIGHT.FLASH);
+        });
+      });
+    });
+
+    it("should handle mixed array of numbers and strings", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          const result = hass.feature.createSupportedFeatures<"light">([
+            LIGHT.EFFECT,
+            "LIGHT.FLASH",
+          ]);
+          expect(result).toBe(LIGHT.EFFECT | LIGHT.FLASH);
+        });
+      });
+    });
+
+    it("should handle invalid feature strings gracefully", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          const result = hass.feature.createSupportedFeatures<"light">([
+            // @ts-expect-error: part of the test
+            "INVALID.DOMAIN",
+            "LIGHT.EFFECT",
+          ]);
+          // Should return only the valid feature, ignoring the invalid one
+          expect(result).toBe(LIGHT.EFFECT);
+        });
+      });
+    });
+  });
+
+  describe("hasFeature", () => {
+    it("should return true when entity has the feature", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          // Use numeric features input instead of entity lookup to avoid test environment issues
+          const features = LIGHT.EFFECT | LIGHT.FLASH;
+          const result = hass.feature.hasFeature(features, LIGHT.EFFECT);
+          expect(result).toBe(true);
+        });
+      });
+    });
+
+    it("should return false when entity does not have the feature", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          // Use numeric features input instead of entity lookup
+          const features = LIGHT.EFFECT; // Only EFFECT, no FLASH
+          const result = hass.feature.hasFeature(features, LIGHT.FLASH);
+          expect(result).toBe(false);
+        });
+      });
+    });
+
+    it("should work with feature string", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          const features = LIGHT.EFFECT | LIGHT.FLASH;
+          const result = hass.feature.hasFeature<"light">(features, "LIGHT.EFFECT");
+          expect(result).toBe(true);
+        });
+      });
+    });
+
+    it("should work with numeric features input", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          const features = LIGHT.EFFECT | LIGHT.FLASH;
+          const result = hass.feature.hasFeature(features, LIGHT.EFFECT);
+          expect(result).toBe(true);
+        });
+      });
+    });
+  });
+
+  describe("getSupportedFeatures", () => {
+    it("should return array of supported feature numbers", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          // Use numeric features input instead of entity lookup
+          const features = LIGHT.EFFECT | LIGHT.FLASH | LIGHT.TRANSITION;
+          const result = hass.feature.getSupportedFeatures(features);
+          expect(result).toEqual([LIGHT.EFFECT, LIGHT.FLASH, LIGHT.TRANSITION]);
+        });
+      });
+    });
+
+    it("should work with numeric features input", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          const features = LIGHT.EFFECT | LIGHT.FLASH;
+          const result = hass.feature.getSupportedFeatures(features);
+          expect(result).toEqual([LIGHT.EFFECT, LIGHT.FLASH]);
+        });
+      });
+    });
+
+    it("should return empty array when no features are supported", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          const features = 0;
+          const result = hass.feature.getSupportedFeatures(features);
+          expect(result).toEqual([]);
+        });
+      });
+    });
+  });
+
+  describe("listEntityFeatures", () => {
+    it("should return array of feature strings for light entity", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          // Use REAL entity reference from fixtures
+          const entity = hass.refBy.id("light.test_light");
+          const result = hass.feature.listEntityFeatures(entity);
+          // light.test_light has supported_features: 44 (LIGHT.EFFECT | LIGHT.FLASH | LIGHT.TRANSITION)
+          expect(result).toEqual(["LIGHT.EFFECT", "LIGHT.FLASH", "LIGHT.TRANSITION"]);
+        });
+      });
+    });
+
+    it("should return array of feature strings for todo entity", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          // Use REAL entity reference from fixtures
+          const entity = hass.refBy.id("todo.test_todo");
+          const result = hass.feature.listEntityFeatures(entity);
+          // todo.test_todo has supported_features: 15 (TODO.CREATE_TODO_ITEM | TODO.DELETE_TODO_ITEM | TODO.UPDATE_TODO_ITEM | TODO.MOVE_TODO_ITEM)
+          expect(result).toEqual([
+            "TODO.CREATE_TODO_ITEM",
+            "TODO.DELETE_TODO_ITEM",
+            "TODO.UPDATE_TODO_ITEM",
+            "TODO.MOVE_TODO_ITEM",
+          ]);
+        });
+      });
+    });
+
+    it("should return array of feature strings for climate entity", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          // Use REAL entity reference from fixtures
+          const entity = hass.refBy.id("climate.test_climate");
+          const result = hass.feature.listEntityFeatures(entity);
+          // climate.test_climate has supported_features: 1 (CLIMATE.TARGET_TEMPERATURE)
+          expect(result).toEqual(["CLIMATE.TARGET_TEMPERATURE"]);
+        });
+      });
+    });
+
+    it("should return empty array for unsupported domain", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          // Use REAL entity reference from fixtures
+          const entity = hass.refBy.id("unsupported.test");
+          // @ts-expect-error part of the test
+          const result = hass.feature.listEntityFeatures(entity);
+          // unsupported.test has supported_features: 1 but domain is unsupported
+          expect(result).toEqual([]);
+        });
+      });
+    });
+
+    it("should return empty array when no features are supported", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          // Use REAL entity reference from fixtures that has no features
+          const entity = hass.refBy.id("sensor.magic");
+          const result = hass.feature.listEntityFeatures(entity);
+          // sensor.magic has supported_features: 0
+          expect(result).toEqual([]);
+        });
+      });
+    });
+  });
+});

package/src/testing/id-by.spec.mts

@@ -100,7 +100,7 @@ describe("enabled entities", () => {
       await hassTestRunner.run(({ lifecycle, hass }) => {
         lifecycle.onReady(() => {
           const synapse = hass.idBy.platform("synapse");
-          expect(synapse.length).toBe(7);
+          expect(synapse.length).toBe(11);
         });
       });
     });
@@ -110,7 +110,7 @@ describe("enabled entities", () => {
       await hassTestRunner.run(({ lifecycle, hass }) => {
         lifecycle.onReady(() => {
           const synapse = hass.idBy.platform("synapse", "light");
-          expect(synapse.length).toBe(0);
+          expect(synapse.length).toBe(1);
         });
       });
     });
@@ -205,7 +205,7 @@ describe("disabled entities", () => {
       await hassTestRunner.run(({ lifecycle, hass }) => {
         lifecycle.onReady(() => {
           const synapse = hass.idBy.platform("synapse");
-          expect(synapse.length).toBe(8);
+          expect(synapse.length).toBe(12);
         });
       });
     });