@digital-alchemy/hass 24.9.3 → 24.9.5

package/src/helpers/registry.ts

@@ -0,0 +1,281 @@
+import { TAreaId, TDeviceId, TFloorId, TLabelId, TPlatformId, TZoneId } from "../dynamic";
+import { ANY_ENTITY } from "./utility.helper";
+
+export type LabelOptions = {
+  name: string;
+  icon: string;
+  color: string;
+};
+
+export type EditLabelOptions = {
+  entity: ANY_ENTITY;
+  label: TLabelId;
+};
+
+export type EditAliasOptions = {
+  entity: ANY_ENTITY;
+  alias: string;
+};
+
+export type LabelDefinition = {
+  color: string;
+  description?: string;
+  icon: string;
+  label_id: TLabelId;
+  name: string;
+};
+
+export type ToggleExpose = {
+  assistants: string | string[];
+  entity_ids: ANY_ENTITY | ANY_ENTITY[];
+  should_expose: boolean;
+};
+
+export type SensorUnitOfMeasurement =
+  | "h"
+  | "min"
+  | "s"
+  | "d"
+  | "K"
+  | "°C"
+  | "°F"
+  | "cm"
+  | "in"
+  | "mm"
+  | "VA"
+  | "L"
+  | "gal"
+  | "m³"
+  | "ft³"
+  | "CCF"
+  | "kg"
+  | "g"
+  | "mg"
+  | "µg"
+  | "oz"
+  | "lb"
+  | "st"
+  | "ft/s"
+  | "km/h"
+  | "kn"
+  | "m/s"
+  | "mph"
+  | "in/d"
+  | "in/h"
+  | "mm/d"
+  | "V"
+  | "mV"
+  | "dB"
+  | "dBm"
+  | "mL"
+  | "fl. oz."
+  | "dBA"
+  | "cbar"
+  | "bar"
+  | "hPa"
+  | "inHg"
+  | "kPa"
+  | "mbar"
+  | "Pa"
+  | "psi"
+  | "var"
+  | "%"
+  | "None"
+  | "W"
+  | "kW"
+  | "µg/m³"
+  | "lx"
+  | "W/m²"
+  | "BTU/(h⋅ft²)"
+  | "Hz"
+  | "kHz"
+  | "MHz"
+  | "GHz"
+  | "Wh"
+  | "kWh"
+  | "MWh"
+  | "MJ"
+  | "GJ"
+  | "km"
+  | "m"
+  | "mi"
+  | "yd"
+  | "bit/s"
+  | "kbit/s"
+  | "Mbit/s"
+  | "Gbit/s"
+  | "B/s"
+  | "kB/s"
+  | "MB/s"
+  | "GB/s"
+  | "KiB/s"
+  | "MiB/s"
+  | "GiB/s"
+  | "bit"
+  | "kbit"
+  | "Mbit"
+  | "Gbit"
+  | "B"
+  | "kB"
+  | "MB"
+  | "GB"
+  | "TB"
+  | "PB"
+  | "EB"
+  | "ZB"
+  | "YB"
+  | "KiB"
+  | "MiB"
+  | "GiB"
+  | "TiB"
+  | "PiB"
+  | "EiB"
+  | "ZiB"
+  | "YiB"
+  | "A"
+  | "mA"
+  | "ppm";
+
+export type EntityRegistryItem<ENTITY extends ANY_ENTITY> = {
+  area_id?: TAreaId;
+  categories: object;
+  config_entry_id?: string;
+  device_id?: TDeviceId;
+  disabled_by?: string;
+  entity_category?: string;
+  entity_id: ENTITY;
+  has_entity_name: boolean;
+  hidden_by?: string;
+  icon?: string;
+  id: string;
+  labels: TLabelId[];
+  name?: string;
+  options: {
+    conversation: {
+      should_expose?: boolean;
+    };
+    sensor?: {
+      display_precision?: number;
+      unit_of_measurement?: SensorUnitOfMeasurement;
+    };
+  };
+  original_name: string;
+  platform: TPlatformId;
+  translation_key?: string;
+  unique_id: string;
+  aliases: string[];
+  capabilities?: string;
+  device_class?: string;
+  original_device_class?: string;
+  original_icon?: string;
+};
+
+export const UPDATE_REGISTRY = "config/entity_registry/update";
+
+export type UpdateCoreOptions = {
+  currency: string;
+  elevation: number;
+  unit_system: string;
+  update_units: boolean;
+  time_zone: string;
+  location_name: string;
+  language: string;
+  country: string;
+};
+
+export type ZoneOptions = {
+  latitude: number;
+  longitude: number;
+  name: string;
+  icon: string;
+  passive: boolean;
+};
+
+export type ZoneDetails = ZoneOptions & { id: TZoneId };
+
+export interface ManifestItem {
+  domain: string;
+  name: string;
+  codeowners: string[];
+  config_flow?: boolean;
+  documentation?: string;
+  iot_class?: IotClass;
+  loggers?: string[];
+  requirements?: string[];
+  is_built_in: boolean;
+  integration_type?: IntegrationType;
+  quality_scale?: QualityScale;
+  dependencies?: string[];
+  dhcp?: DHCP[];
+  after_dependencies?: string[];
+  single_config_entry?: boolean;
+  bluetooth?: Bluetooth[];
+  version?: string;
+  homekit?: Homekit;
+  zeroconf?: Array<ZeroconfClass | string>;
+  ssdp?: SSDP[];
+  issue_tracker?: string;
+}
+
+export interface Bluetooth {
+  manufacturer_id: number;
+  service_uuid?: string;
+  manufacturer_data_start?: number[];
+}
+
+export interface DHCP {
+  registered_devices?: boolean;
+  hostname?: string;
+  macaddress?: string;
+}
+
+export interface Homekit {
+  models: string[];
+}
+
+export enum IntegrationType {
+  Device = "device",
+  Entity = "entity",
+  Helper = "helper",
+  Hub = "hub",
+  Service = "service",
+  System = "system",
+}
+
+export enum IotClass {
+  Calculated = "calculated",
+  CloudPolling = "cloud_polling",
+  CloudPush = "cloud_push",
+  LocalPolling = "local_polling",
+  LocalPush = "local_push",
+}
+
+export enum QualityScale {
+  Internal = "internal",
+  Platinum = "platinum",
+}
+
+export interface SSDP {
+  manufacturer: string;
+  modelDescription: string;
+}
+
+export interface ZeroconfClass {
+  type: string;
+  properties?: Properties;
+}
+
+export interface Properties {
+  mdl?: string;
+  SYSTYPE?: string;
+}
+
+export type FloorCreate = {
+  name: string;
+  level: number;
+  aliases?: string[];
+};
+
+export type FloorDetails = FloorCreate & {
+  floor_id: TFloorId;
+};

package/src/helpers/utility.helper.ts

@@ -0,0 +1,147 @@
+import { is, TBlackHole } from "@digital-alchemy/core";
+import { Dayjs } from "dayjs";
+import { Get } from "type-fest";
+
+import {
+  ENTITY_SETUP,
+  iCallService,
+  REGISTRY_SETUP,
+  TAreaId,
+  TDeviceId,
+  TFloorId,
+  TLabelId,
+  TPlatformId,
+  TRawDomains,
+  TRawEntityIds,
+} from "../dynamic";
+import { HassEntityContext } from ".";
+
+export type ANY_ENTITY = TRawEntityIds;
+
+// ? Casting by domain turns things from "equiv to ANY_ENTITY" to "scene.*" type generics
+// These are no longer valid comparisons against ANY_ENTITY though
+// ? The extract converts those generic types back into real entity ids to make types valid again
+/**
+ * Pick any valid entity, optionally limiting by domain
+ */
+export type PICK_ENTITY<DOMAIN extends ALL_DOMAINS = ALL_DOMAINS> = Extract<
+  ANY_ENTITY,
+  `${DOMAIN}.${string}`
+>;
+
+/**
+ * Pick any valid service call, optionally limiting by domain
+ */
+export type PICK_SERVICE<DOMAIN extends ALL_SERVICE_DOMAINS = ALL_SERVICE_DOMAINS> = {
+  [key in DOMAIN]: `${key}.${keyof iCallService[key] & string}`;
+}[DOMAIN];
+
+export type PICK_SERVICE_PARAMETERS<
+  DOMAINS extends ALL_SERVICE_DOMAINS,
+  SERVICE extends PICK_SERVICE<DOMAINS>,
+> =
+  Get<iCallService, SERVICE> extends (serviceParams: infer ServiceParams) => TBlackHole
+    ? ServiceParams
+    : never;
+
+export function entity_split(
+  entity: { entity_id: ANY_ENTITY } | ANY_ENTITY,
+): [ALL_DOMAINS, string] {
+  if (is.object(entity)) {
+    entity = entity.entity_id;
+  }
+  return entity.split(".") as [ALL_DOMAINS, string];
+}
+/**
+ * Extract the domain from an entity with type safety
+ */
+export function domain(entity: { entity_id: ANY_ENTITY } | ANY_ENTITY): ALL_DOMAINS {
+  if (is.object(entity)) {
+    entity = entity.entity_id;
+  }
+  return entity_split(entity).shift() as ALL_DOMAINS;
+}
+
+export type ENTITY_PROP<ENTITY_ID extends PICK_ENTITY, PROP extends "state" | "attributes"> = Get<
+  ENTITY_SETUP,
+  `${ENTITY_ID}.${PROP}`
+>;
+
+/**
+ * Type definitions to match a specific entity.
+ */
+export type ENTITY_STATE<ENTITY_ID extends ANY_ENTITY> = Omit<
+  ENTITY_SETUP[ENTITY_ID],
+  "state" | "context" | "last_changed" | "last_updated" | "entity_id" | "attributes"
+> & {
+  last_reported: Dayjs;
+  last_changed: Dayjs;
+  last_updated: Dayjs;
+  attributes: ENTITY_SETUP[ENTITY_ID]["attributes"];
+  entity_id: ENTITY_ID;
+  state: ENTITY_SETUP[ENTITY_ID]["state"];
+  context: HassEntityContext;
+};
+
+/**
+ * Union of all domains that contain entities
+ */
+export type ALL_DOMAINS = TRawDomains;
+
+/**
+ * Union of all services with callable methods
+ */
+export type ALL_SERVICE_DOMAINS = keyof iCallService;
+
+export type GetDomain<ENTITY extends ANY_ENTITY> = ENTITY extends `${infer domain}.${string}`
+  ? domain
+  : never;
+
+function isDomain<DOMAIN extends ALL_DOMAINS>(
+  entity: string,
+  domain: DOMAIN | DOMAIN[],
+): entity is PICK_ENTITY<DOMAIN> {
+  const [test] = entity.split(".") as [DOMAIN, string];
+  return [domain].flat().includes(test);
+}
+
+is.domain = isDomain;
+
+declare module "@digital-alchemy/core" {
+  export interface IsIt {
+    /**
+     * Check to see if an entity matches
+     */
+    domain: typeof isDomain;
+  }
+}
+
+export const PostConfigPriorities = {
+  FETCH: 1,
+  VALIDATE: -1,
+} as const;
+
+export type PICK_FROM_AREA<ID extends TAreaId, DOMAIN extends ALL_DOMAINS = ALL_DOMAINS> = Extract<
+  REGISTRY_SETUP["area"][`_${ID}`],
+  PICK_ENTITY<DOMAIN>
+>;
+
+export type PICK_FROM_LABEL<
+  ID extends TLabelId,
+  DOMAIN extends ALL_DOMAINS = ALL_DOMAINS,
+> = Extract<REGISTRY_SETUP["label"][`_${ID}`], PICK_ENTITY<DOMAIN>>;
+
+export type PICK_FROM_FLOOR<
+  ID extends TFloorId,
+  DOMAIN extends ALL_DOMAINS = ALL_DOMAINS,
+> = Extract<REGISTRY_SETUP["floor"][`_${ID}`], PICK_ENTITY<DOMAIN>>;
+
+export type PICK_FROM_DEVICE<
+  ID extends TDeviceId,
+  DOMAIN extends ALL_DOMAINS = ALL_DOMAINS,
+> = Extract<REGISTRY_SETUP["device"][`_${ID}`], PICK_ENTITY<DOMAIN>>;
+
+export type PICK_FROM_PLATFORM<
+  ID extends TPlatformId,
+  DOMAIN extends ALL_DOMAINS = ALL_DOMAINS,
+> = Extract<REGISTRY_SETUP["platform"][`_${ID}`], PICK_ENTITY<DOMAIN>>;

package/src/helpers/websocket.helper.ts

@@ -0,0 +1,117 @@
+import { TBlackHole, TContext } from "@digital-alchemy/core";
+import { Dayjs } from "dayjs";
+
+import { HassSocketMessageTypes } from "./constants.helper";
+import { EntityUpdateEvent } from "./entity-state.helper";
+import { ALL_DOMAINS, ANY_ENTITY, ENTITY_STATE, PICK_ENTITY } from "./utility.helper";
+
+export interface SignRequestResponse {
+  path: string;
+}
+
+export interface SocketMessageDTO {
+  error?: Record<string, unknown>;
+  event?: EntityUpdateEvent;
+  id: string | number;
+  message?: string;
+  result?: Record<string, unknown> | Array<unknown>;
+  type: `${HassSocketMessageTypes}`;
+}
+
+export type SocketSubscribeOptions<EVENT extends string> = {
+  event_type: EVENT;
+  context: TContext;
+  exec: (data: SocketSubscribeData<EVENT>) => TBlackHole;
+};
+
+export type SocketSubscribeData<EVENT extends string> = {
+  event_type: EVENT;
+};
+
+export interface SendSocketMessageDTO {
+  access_token?: string;
+  disabled_by?: "user";
+  domain?: string;
+  hidden_by?: "user";
+  service?: string;
+  service_data?: unknown;
+  type: string;
+}
+
+export interface UpdateEntityMessageDTO<DOMAIN extends ALL_DOMAINS = ALL_DOMAINS> {
+  area_id?: string;
+  disabled_by?: "user";
+  entity_id: PICK_ENTITY<DOMAIN>;
+  hidden_by?: "user";
+  icon?: string;
+  name: string;
+  new_entity_id: PICK_ENTITY<DOMAIN>;
+  type: "config/entity_registry/update";
+}
+
+export interface RemoveEntityMessageDTO {
+  entity_id: ANY_ENTITY;
+  type: "config/entity_registry/remove";
+}
+
+export interface FindRelatedDTO {
+  item_id: string;
+  item_type: string;
+  type: "search/related";
+}
+
+export interface RegistryGetDTO {
+  entity_id: string;
+  type: "config/entity_registry/get";
+}
+
+export interface RenderTemplateDTO {
+  template: string;
+  timeout: number;
+  type: "render_template";
+}
+
+export interface SubscribeTriggerDTO {
+  trigger: Record<string, unknown>;
+  type: "subscribe_trigger";
+}
+
+export interface UnsubscribeEventsDTO {
+  subscription: number;
+  type: "unsubscribe_events";
+}
+
+export interface SignPathDTO {
+  path: string;
+  type: "auth/sign_path";
+}
+
+export interface RemoveBackupDTO {
+  slug: string;
+  type: "backup/remove";
+}
+
+export interface EntityHistoryDTO<ENTITIES extends ANY_ENTITY[] = ANY_ENTITY[]> {
+  end_time: Date | string | Dayjs;
+  entity_ids: ENTITIES;
+  minimal_response?: boolean;
+  no_attributes?: boolean;
+  start_time: Date | string | Dayjs;
+  type: "history/history_during_period";
+}
+
+export type EntityHistoryResult<
+  ENTITY extends ANY_ENTITY = ANY_ENTITY,
+  ATTRIBUTES extends object = object,
+> = Pick<ENTITY_STATE<ENTITY> & { attributes: ATTRIBUTES }, "attributes" | "state"> & {
+  date: Date;
+};
+
+export type OnHassEventCallback<T = object> = (event: T) => TBlackHole;
+
+export type OnHassEventOptions<T = object> = {
+  context: TContext;
+  exec: OnHassEventCallback<T>;
+  event: string;
+  once?: boolean;
+};

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./dynamic";
+export * from "./extensions";
+export * from "./hass.module";
+export * from "./helpers";
+export * from "./quickboot.module";

package/src/mock_assistant/extensions/area.extension.ts

@@ -0,0 +1,62 @@
+import { TServiceParams } from "@digital-alchemy/core";
+
+import { TAreaId } from "../../dynamic";
+import { AreaDetails } from "../../helpers";
+
+export function MockAreaExtension({ mock_assistant }: TServiceParams) {
+  let areas = new Map<TAreaId, AreaDetails>();
+
+  mock_assistant.socket.onMessage("config/area_registry/list", message => {
+    mock_assistant.socket.sendMessage({
+      id: message.id,
+      result: [...areas.values()],
+      type: "result",
+    });
+  });
+
+  mock_assistant.socket.onMessage<{ area_id: TAreaId }>("config/area_registry/delete", message => {
+    areas.delete(message.area_id);
+    sendUpdate();
+    mock_assistant.socket.sendMessage({
+      id: message.id,
+      result: null,
+      type: "result",
+    });
+  });
+
+  mock_assistant.socket.onMessage<AreaDetails>("config/area_registry/create", message => {
+    message.area_id = message.name as TAreaId;
+    areas.set(message.area_id as TAreaId, message);
+    sendUpdate();
+    mock_assistant.socket.sendMessage({
+      id: message.id,
+      result: null,
+      type: "result",
+    });
+  });
+
+  mock_assistant.socket.onMessage<AreaDetails>("config/area_registry/update", message => {
+    areas.set(message.area_id as TAreaId, message);
+    sendUpdate();
+    mock_assistant.socket.sendMessage({
+      id: message.id,
+      result: null,
+      type: "result",
+    });
+  });
+
+  const sendUpdate = () =>
+    mock_assistant.socket.sendMessage({
+      event: { event_type: "area_registry_updated" },
+      type: "event",
+    });
+
+  return {
+    /**
+     * @internal
+     */
+    loadFixtures(incoming: AreaDetails[]) {
+      areas = new Map(incoming.map(i => [i.area_id, i]));
+    },
+  };
+}

package/src/mock_assistant/extensions/config.extension.ts

@@ -0,0 +1,33 @@
+import { deepExtend, TServiceParams } from "@digital-alchemy/core";
+
+import { HassConfig } from "../../helpers";
+
+export function MockConfig({ hass }: TServiceParams) {
+  let config = { components: ["synapse"], version: "2024.4.1" } as HassConfig;
+
+  const origConfig = hass.fetch.getConfig;
+  hass.fetch.getConfig = async () => config;
+
+  return {
+    current() {
+      return config;
+    },
+    /**
+     * @internal
+     */
+    loadFixtures(incoming: HassConfig) {
+      if (incoming) {
+        config = incoming;
+      }
+    },
+    merge(incoming: Partial<HassConfig>) {
+      config = deepExtend(config, incoming);
+    },
+    /**
+     * @internal
+     */
+    monkeyReset() {
+      hass.fetch.getConfig = origConfig;
+    },
+  };
+}

package/src/mock_assistant/extensions/device.extension.ts

@@ -0,0 +1,44 @@
+import { TServiceParams } from "@digital-alchemy/core";
+
+import { TDeviceId } from "../../dynamic";
+import { DEVICE_REGISTRY_UPDATED, DeviceDetails } from "../../helpers";
+
+export function MockDeviceExtension({ mock_assistant }: TServiceParams) {
+  let devices = new Map<TDeviceId, DeviceDetails>();
+
+  mock_assistant.socket.onMessage("config/device_registry/list", message => {
+    mock_assistant.socket.sendMessage({
+      id: message.id,
+      result: [...devices.values()],
+      type: "result",
+    });
+  });
+
+  mock_assistant.socket.onMessage<{ device_id: TDeviceId }>(
+    "config/device_registry/delete",
+    message => {
+      devices.delete(message.device_id);
+      sendUpdate();
+      mock_assistant.socket.sendMessage({
+        id: message.id,
+        result: null,
+        type: "result",
+      });
+    },
+  );
+
+  const sendUpdate = () =>
+    mock_assistant.socket.sendMessage({
+      event: { event_type: DEVICE_REGISTRY_UPDATED },
+      type: "event",
+    });
+
+  return {
+    /**
+     * @internal
+     */
+    loadFixtures(incoming: DeviceDetails[]) {
+      devices = new Map(incoming.map(i => [i.id, i]));
+    },
+  };
+}