@digital-alchemy/hass 24.9.4 → 24.9.5

package/src/hass.module.ts

@@ -0,0 +1,217 @@
+import { CreateLibrary } from "@digital-alchemy/core";
+
+import {
+  Area,
+  Backup,
+  CallProxy,
+  Configure,
+  Device,
+  EntityManager,
+  Events,
+  FetchAPI,
+  FetchInternals,
+  Floor,
+  IDByExtension,
+  Label,
+  ReferenceExtension,
+  Registry,
+  WebsocketAPI,
+  Zone,
+} from "./extensions";
+
+export const LIB_HASS = CreateLibrary({
+  configuration: {
+    /**
+     * Where to reach Home Assistant at
+     *
+     * Will auto detect inside an addon
+     */
+    BASE_URL: {
+      default: "http://homeassistant.local:8123",
+      description: "Url to reach Home Assistant at",
+      type: "string",
+    },
+
+    /**
+     * When adding new integrations, app will receive 1 update event for everything that changes.
+     * This can result in a flood of updates where only a single one is needed at the very end.
+     *
+     * This setting helps control that.
+     */
+    EVENT_DEBOUNCE_MS: {
+      default: 50,
+      description: "Debounce reactions to registry changes",
+      type: "number",
+    },
+
+    /**
+     * ## ACKNOWLEDGE ME
+     *
+     * Home Assistant **should** respond to all sent messages with a reply to confirm it was received.
+     *
+     * If this does not happen, then a warning will be emitted into the logs
+     */
+    EXPECT_RESPONSE_AFTER: {
+      default: 5,
+      description:
+        "If sendMessage was set to expect a response, a warning will be emitted after this delay if one is not received",
+      type: "number",
+    },
+
+    /**
+     * General purpose variable, adds delays to things when retrying
+     *
+     * > **NOTE**: this is best set to `0` for unit tests
+     */
+    RETRY_INTERVAL: {
+      default: 5,
+      description: "How often to retry connecting on connection failure (seconds)",
+      type: "number",
+    },
+
+    /**
+     * @internal
+     */
+    SOCKET_AVG_DURATION: {
+      default: 5,
+      description:
+        "How many seconds worth of requests to use in avg for math in REQ_PER_SEC calculations",
+      type: "number",
+    },
+
+    /**
+     * @internal
+     */
+    SOCKET_CRASH_REQUESTS_PER_SEC: {
+      default: 500,
+      description:
+        "Socket service will commit sudoku if more than this many outgoing messages are sent to Home Assistant in a second. Usually indicates runaway code",
+      type: "number",
+    },
+
+    /**
+     * @internal
+     */
+    SOCKET_WARN_REQUESTS_PER_SEC: {
+      default: 300,
+      description:
+        "Emit warnings if the home controller attempts to send more than X messages to Home Assistant inside of a second",
+      type: "number",
+    },
+
+    /**
+     * Long lived access token
+     */
+    TOKEN: {
+      description: "Long lived access token to Home Assistant",
+      required: true,
+      type: "string",
+    },
+
+    /**
+     * Intended to be provided via command line switch. Ex:
+     *
+     * ```bash
+     * $ node dist/main.js --validate-configuration
+     * ```
+     */
+    VALIDATE_CONFIGURATION: {
+      default: false,
+      description: "Validate the credentials then quit",
+      type: "boolean",
+    },
+  },
+  name: "hass",
+  // no internal dependency ones first
+  priorityInit: ["internals", "fetch", "socket"],
+  services: {
+    /**
+     * home assistant areas
+     */
+    area: Area,
+
+    /**
+     * home assistant backup interactions
+     */
+    backup: Backup,
+
+    /**
+     * general service calling interface
+     */
+    call: CallProxy,
+
+    /**
+     * internal tools
+     */
+    configure: Configure,
+
+    /**
+     * device interactions
+     */
+    device: Device,
+
+    /**
+     * retrieve and interact with home assistant entities
+     */
+    entity: EntityManager,
+
+    /**
+     * named event attachments
+     */
+    events: Events,
+
+    /**
+     * rest api commands
+     */
+    fetch: FetchAPI,
+
+    /**
+     * floors, like groups of areas
+     */
+    floor: Floor,
+
+    /**
+     * search for entity ids in a type safe way
+     */
+    idBy: IDByExtension,
+
+    /**
+     * @internal
+     */
+    internals: FetchInternals,
+
+    /**
+     * home assistant label interactions
+     */
+    label: Label,
+
+    /**
+     * obtain references to entities
+     */
+    refBy: ReferenceExtension,
+
+    /**
+     * interact with the home assistant registry
+     */
+    registry: Registry,
+
+    /**
+     * websocket interface
+     */
+    socket: WebsocketAPI,
+
+    /**
+     * zone interactions
+     */
+    zone: Zone,
+  },
+});
+
+declare module "@digital-alchemy/core" {
+  export interface LoadedModules {
+    /**
+     * tools for interacting with home assistant
+     */
+    hass: typeof LIB_HASS;
+  }
+}

package/src/helpers/backup.helper.ts

@@ -0,0 +1,11 @@
+export interface HomeAssistantBackup {
+  date: string;
+  name: string;
+  path: string;
+  size: number;
+  slug: string;
+}
+export interface BackupResponse {
+  backing_up: boolean;
+  backups: HomeAssistantBackup[];
+}

package/src/helpers/constants.helper.ts

@@ -0,0 +1,30 @@
+export const HASS_ENTITY = "HASS_ENTITY";
+export const HASS_ENTITY_GROUP = "HASS_ENTITY_GROUP";
+export const ALL_ENTITIES_UPDATED = "ALL_ENTITIES_UPDATED";
+export const SOCKET_READY = "SOCKET_READY";
+
+export enum HassSocketMessageTypes {
+  auth_required = "auth_required",
+  auth_ok = "auth_ok",
+  event = "event",
+  result = "result",
+  pong = "pong",
+  auth_invalid = "auth_invalid",
+}
+
+export const HOME_ASSISTANT_MODULE_CONFIGURATION = "HOME_ASSISTANT_MODULE_CONFIGURATION";
+
+/**
+ * Required for label support, which is an automatic process at boot
+ *
+ * Will not make feature optional to support older hass versions
+ * Update your stuff
+ */
+export const MIN_SUPPORTED_HASS_VERSION = "2024.4.0";
+export const EARLY_ON_READY = 1;
+export const ENTITY_REGISTRY_UPDATED = "ENTITY_REGISTRY_UPDATED";
+export const AREA_REGISTRY_UPDATED = "AREA_REGISTRY_UPDATED";
+export const LABEL_REGISTRY_UPDATED = "LABEL_REGISTRY_UPDATED";
+export const FLOOR_REGISTRY_UPDATED = "FLOOR_REGISTRY_UPDATED";
+export const DEVICE_REGISTRY_UPDATED = "DEVICE_REGISTRY_UPDATED";
+export const ZONE_REGISTRY_UPDATED = "ZONE_REGISTRY_UPDATED";

package/src/helpers/device.helper.ts

@@ -0,0 +1,25 @@
+import { TDeviceId } from "../dynamic";
+
+export interface DeviceDetails {
+  area_id: null | string;
+  configuration_url: null | string;
+  config_entries: string[];
+  connections: Array<string[]>;
+  disabled_by: null;
+  entry_type: EntryType | null;
+  hw_version: null | string;
+  id: TDeviceId;
+  identifiers: Array<Array<number | string>>;
+  labels: string[];
+  manufacturer: null | string;
+  model: null | string;
+  name_by_user: null | string;
+  name: string;
+  serial_number: null;
+  sw_version: null | string;
+  via_device_id: TDeviceId;
+}
+
+export enum EntryType {
+  Service = "service",
+}

package/src/helpers/entity-state.helper.ts

@@ -0,0 +1,171 @@
+import { FIRST, TBlackHole } from "@digital-alchemy/core";
+import { Dayjs } from "dayjs";
+import { Except } from "type-fest";
+
+import { iCallService, TAreaId, TDeviceId, TLabelId, TPlatformId, TRawDomains } from "../dynamic";
+import { SensorUnitOfMeasurement } from "./registry";
+import {
+  ALL_DOMAINS,
+  ALL_SERVICE_DOMAINS,
+  ANY_ENTITY,
+  ENTITY_STATE,
+  GetDomain,
+  PICK_ENTITY,
+} from "./utility.helper";
+
+export interface HassEntityContext {
+  id: string | null;
+  parent_id: string | null;
+  user_id: string | null;
+}
+
+type GenericEntityAttributes = {
+  /**
+   * Entity groups
+   */
+  entity_id?: ANY_ENTITY[];
+  /**
+   * Human readable name
+   */
+  friendly_name?: string;
+};
+
+export type EntityHistoryItem = { a: object; s: unknown; lu: number };
+
+export type TEntityUpdateCallback<ENTITY_ID extends ANY_ENTITY> = (
+  new_state: NonNullable<ENTITY_STATE<ENTITY_ID>>,
+  old_state: NonNullable<ENTITY_STATE<ENTITY_ID>>,
+  remove: () => TBlackHole,
+) => TBlackHole;
+
+export type RemovableCallback<ENTITY_ID extends ANY_ENTITY> = (
+  callback: TEntityUpdateCallback<ENTITY_ID>,
+) => {
+  remove: () => void;
+};
+
+export type ByIdProxy<ENTITY_ID extends ANY_ENTITY> = ENTITY_STATE<ENTITY_ID> & {
+  entity_id: ENTITY_ID;
+  /**
+   * Run callback
+   */
+  onUpdate: RemovableCallback<ENTITY_ID>;
+  /**
+   * Retrieve state changes for an entity in a date range
+   */
+  history: (from: Dayjs | Date, to: Dayjs | Date) => Promise<ENTITY_STATE<ENTITY_ID>[]>;
+  /**
+   * Run callback once, for next update
+   */
+  once: (callback: TEntityUpdateCallback<ENTITY_ID>) => void;
+  /**
+   * Will resolve with the next state of the next value. No time limit
+   */
+  nextState: (timeoutMs?: number) => Promise<ENTITY_STATE<ENTITY_ID>>;
+  /**
+   * Will resolve when state
+   */
+  waitForState: (state: string | number, timeoutMs?: number) => Promise<ENTITY_STATE<ENTITY_ID>>;
+  /**
+   * Access the immediate previous entity state
+   */
+  previous: ENTITY_STATE<ENTITY_ID>;
+  /**
+   * Remove all `.onUpdate` listeners for this entity
+   *
+   * If you want to remove a particular one, use use the return value of the `.onUpdate` call instead
+   */
+  removeAllListeners: () => void;
+} & (GetDomain<ENTITY_ID> extends ALL_SERVICE_DOMAINS
+    ? DomainServiceCalls<GetDomain<ENTITY_ID>>
+    : object);
+
+type DomainServiceCalls<DOMAIN extends Extract<ALL_DOMAINS, ALL_SERVICE_DOMAINS>> = {
+  [SERVICE in Extract<keyof iCallService[DOMAIN], string>]: CallRewrite<DOMAIN, SERVICE>;
+};
+
+type CallRewrite<
+  D extends Extract<ALL_DOMAINS, ALL_SERVICE_DOMAINS>,
+  S extends keyof iCallService[D],
+> = (
+  // @ts-expect-error fix another day, the transformation is valid
+  data?: Except<Parameters<iCallService[D][S]>[typeof FIRST], "entity_id">,
+) => Promise<void>;
+
+export interface GenericEntityDTO<
+  ATTRIBUTES extends object = GenericEntityAttributes,
+  STATE extends unknown = string,
+  CONTEXT extends HassEntityContext = HassEntityContext,
+  DOMAIN extends TRawDomains = TRawDomains,
+> {
+  attributes: ATTRIBUTES;
+  context: CONTEXT;
+  entity_id: PICK_ENTITY<DOMAIN>;
+  last_changed: string;
+  last_updated: string;
+  state: STATE;
+}
+
+export interface EventData<ID extends ANY_ENTITY = ANY_ENTITY> {
+  entity_id?: ID;
+  event?: number;
+  id?: string;
+  new_state?: ENTITY_STATE<ID>;
+  old_state?: ENTITY_STATE<ID>;
+}
+export type EntityUpdateEvent<
+  ID extends ANY_ENTITY = ANY_ENTITY,
+  CONTEXT extends HassEntityContext = HassEntityContext,
+> = {
+  context: CONTEXT;
+  data: EventData<ID>;
+  event_type: string;
+  origin: "local";
+  result?: string;
+  time_fired: Date;
+  variables: Record<string, unknown>;
+};
+
+export interface EntityDetails<ENTITY extends ANY_ENTITY> {
+  area_id: TAreaId;
+  categories: Categories;
+  config_entry_id: null | string;
+  device_id: TDeviceId;
+  disabled_by: string | null;
+  entity_category: string | null;
+  entity_id: ENTITY;
+  has_entity_name: boolean;
+  hidden_by: string | null;
+  icon: null;
+  id: string;
+  labels: TLabelId[];
+  name: null | string;
+  options: Options;
+  original_name: null | string;
+  platform: TPlatformId;
+  translation_key: null | string;
+  unique_id: string;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface Categories {}
+
+export interface Options {
+  conversation: Conversation;
+  "sensor.private"?: SensorPrivate;
+  sensor?: Sensor;
+}
+
+export interface Conversation {
+  should_expose: boolean;
+}
+
+export interface Sensor {
+  suggested_display_precision?: number;
+  display_precision?: null;
+  unit_of_measurement?: SensorUnitOfMeasurement;
+}
+
+export interface SensorPrivate {
+  suggested_unit_of_measurement: string;
+}