@digital-alchemy/hass 24.9.4 → 24.9.5

package/src/extensions/area.extension.ts

@@ -0,0 +1,118 @@
+import { debounce, eachSeries, InternalError, TServiceParams } from "@digital-alchemy/core";
+
+import { TAreaId } from "../dynamic";
+import {
+  ANY_ENTITY,
+  AREA_REGISTRY_UPDATED,
+  AreaCreate,
+  AreaDetails,
+  EARLY_ON_READY,
+  ENTITY_REGISTRY_UPDATED,
+  HassAreaService,
+} from "../helpers";
+
+export function Area({
+  hass,
+  context,
+  config,
+  logger,
+  event,
+  lifecycle,
+}: TServiceParams): HassAreaService {
+  hass.socket.onConnect(async () => {
+    let loading = new Promise<void>(async done => {
+      hass.area.current = await hass.area.list();
+      loading = undefined;
+      done();
+    });
+    lifecycle.onReady(async () => loading && (await loading), EARLY_ON_READY);
+
+    hass.socket.subscribe({
+      context,
+      event_type: "area_registry_updated",
+      async exec() {
+        await debounce(AREA_REGISTRY_UPDATED, config.hass.EVENT_DEBOUNCE_MS);
+        hass.area.current = await hass.area.list();
+        logger.debug(`area registry updated`);
+        event.emit(AREA_REGISTRY_UPDATED);
+      },
+    });
+  });
+
+  async function list() {
+    return await hass.socket.sendMessage<AreaDetails[]>({
+      type: "config/area_registry/list",
+    });
+  }
+
+  async function deleteArea(area_id: TAreaId) {
+    return await new Promise<void>(async done => {
+      event.once(AREA_REGISTRY_UPDATED, done);
+      await hass.socket.sendMessage({
+        area_id,
+        type: "config/area_registry/delete",
+      });
+    });
+  }
+
+  async function create(details: AreaCreate) {
+    return await new Promise<void>(async done => {
+      event.once(AREA_REGISTRY_UPDATED, done);
+      await hass.socket.sendMessage({
+        floor_id: "",
+        icon: "",
+        labels: [],
+        picture: "",
+        type: "config/area_registry/create",
+        ...details,
+      });
+    });
+  }
+
+  async function apply(area: TAreaId, entities: ANY_ENTITY[]) {
+    const out = { updated: [] as ANY_ENTITY[] };
+    await eachSeries(entities, async (entity: ANY_ENTITY) => {
+      const details = hass.entity.registry.current.find(item => item.entity_id === entity);
+      if (!details) {
+        throw new InternalError(
+          context,
+          "UNKNOWN_ENTITY",
+          `Cannot find ${entity} in entity registry`,
+        );
+      }
+      if (details.area_id === area) {
+        return;
+      }
+      await new Promise<void>(async done => {
+        event.once(ENTITY_REGISTRY_UPDATED, done);
+        logger.trace({ area, entity }, `setting area`);
+        out.updated.push(entity);
+        await hass.socket.sendMessage({
+          area_id: area,
+          entity_id: entity,
+          type: "config/entity_registry/update",
+        });
+      });
+    });
+    return out;
+  }
+
+  async function update(details: AreaDetails) {
+    return await new Promise<void>(async done => {
+      event.once(AREA_REGISTRY_UPDATED, done);
+      await hass.socket.sendMessage({
+        type: "config/area_registry/update",
+        ...details,
+      });
+    });
+  }
+
+  return {
+    apply,
+    create,
+    current: [] as AreaDetails[],
+    delete: deleteArea,
+    list,
+    update,
+  };
+}

package/src/extensions/backup.extension.ts

@@ -0,0 +1,63 @@
+import { is, SECOND, sleep, TServiceParams } from "@digital-alchemy/core";
+
+import {
+  BackupResponse,
+  HassBackupService,
+  HomeAssistantBackup,
+  SignRequestResponse,
+} from "../helpers";
+
+export function Backup({ logger, hass, config }: TServiceParams): HassBackupService {
+  async function download(slug: string, destination: string): Promise<void> {
+    const result = await hass.socket.sendMessage<SignRequestResponse>({
+      path: `/api/backup/download/${slug}`,
+      type: "auth/sign_path",
+    });
+    if (!is.object(result) || !("path" in result)) {
+      return;
+    }
+    await hass.fetch.download(destination, {
+      url: result.path,
+    });
+  }
+
+  async function generate(): Promise<HomeAssistantBackup> {
+    let current = await hass.backup.list();
+    // const originalLength = current.backups.length;
+    if (current.backing_up) {
+      logger.warn(
+        { name: generate },
+        `a backup is currently in progress. waiting for that to complete instead`,
+      );
+    } else {
+      logger.info({ name: generate }, "initiating new backup");
+      hass.socket.sendMessage({ type: "backup/generate" });
+      while (current.backing_up === false) {
+        logger.debug({ name: generate }, "... waiting");
+        await sleep(config.hass.RETRY_INTERVAL * SECOND);
+        current = await hass.backup.list();
+      }
+    }
+    while (current.backing_up === true) {
+      logger.debug({ name: generate }, "... waiting");
+      await sleep(config.hass.RETRY_INTERVAL * SECOND);
+      current = await hass.backup.list();
+    }
+    logger.info({ name: generate }, `backup complete`);
+    return current.backups.pop();
+  }
+
+  async function list(): Promise<BackupResponse> {
+    logger.trace({ name: list }, "send");
+    return await hass.socket.sendMessage<BackupResponse>({
+      type: "backup/info",
+    });
+  }
+
+  async function remove(slug: string): Promise<void> {
+    logger.trace({ name: remove }, "send");
+    await hass.socket.sendMessage({ slug, type: "backup/remove" });
+  }
+
+  return { download, generate, list, remove };
+}

package/src/extensions/call-proxy.extension.ts

@@ -0,0 +1,113 @@
+import { is, TServiceParams } from "@digital-alchemy/core";
+
+import { ALL_SERVICE_DOMAINS, iCallService, PICK_SERVICE, PICK_SERVICE_PARAMETERS } from "..";
+
+export function CallProxy({ logger, lifecycle, internal, hass }: TServiceParams): iCallService {
+  let loaded = false;
+  const rawProxy = {} as Record<string, Record<string, unknown>>;
+  /**
+   * Describe the current services, and build up a proxy api based on that.
+   *
+   * This API matches the api at the time the this function is run, which may be different from any generated typescript definitions from the past.
+   */
+  lifecycle.onBootstrap(async () => {
+    logger.debug({ name: "onBootstrap" }, `runtime populate service interfaces`);
+    await loadServiceList();
+    loaded = true;
+  });
+
+  async function loadServiceList(): Promise<void> {
+    await hass.configure.loadServiceList();
+    const services = hass.configure.getServices();
+    services.forEach(value => {
+      const services = Object.keys(value.services);
+
+      rawProxy[value.domain] = Object.fromEntries(
+        Object.entries(value.services).map(([key]) => [
+          key,
+          async <SERVICE extends PICK_SERVICE<ALL_SERVICE_DOMAINS>>(parameters: object) => {
+            const data = value.services[key];
+
+            const service = `${value.domain}.${key}` as SERVICE;
+            return await sendMessage(
+              service,
+              {
+                ...parameters,
+              } as PICK_SERVICE_PARAMETERS<ALL_SERVICE_DOMAINS, SERVICE>,
+              is.boolean(data?.response?.optional),
+            );
+          },
+        ]),
+      );
+      logger.trace({ name: loadServiceList, services }, `loaded domain [%s]`, value.domain);
+    });
+  }
+
+  /**
+   * Prefer sending via socket, if available.
+   */
+  async function sendMessage<
+    DOMAIN extends ALL_SERVICE_DOMAINS,
+    SERVICE extends PICK_SERVICE<DOMAIN>,
+  >(
+    serviceName: SERVICE,
+    service_data: PICK_SERVICE_PARAMETERS<DOMAIN, SERVICE>,
+    return_response: boolean,
+  ) {
+    // pause for rest also
+    if (hass.socket.pauseMessages) {
+      return undefined;
+    }
+    const [domain, service] = serviceName.split(".");
+    // User can just not await this call if they don't care about the "waitForChange"
+
+    if (!return_response) {
+      return await hass.socket.sendMessage(
+        { domain, service, service_data, type: "call_service" },
+        true,
+      );
+    }
+    const result = (await hass.socket.sendMessage(
+      { domain, return_response, service, service_data, type: "call_service" },
+      true,
+    )) as { response: unknown };
+    if (!result?.response) {
+      logger.warn({ result }, `{%s}.{%s} did not return a response`, domain, service);
+    }
+    return result?.response;
+  }
+
+  function buildCallProxy(): iCallService {
+    return new Proxy(rawProxy as iCallService, {
+      get: (_, domain: ALL_SERVICE_DOMAINS) => {
+        // oddities in the way proxies work
+        // this situation isn't testable afaik
+        if (!internal.boot.constructComplete.has("hass")) {
+          return undefined;
+        }
+        if (!loaded) {
+          lifecycle.onReady(() => {
+            logger.error(
+              `attempted to use {hass.call} before data loaded. use {lifecycle.onReady}`,
+            );
+            // eslint-disable-next-line no-console
+            console.trace(`hass.call`);
+          });
+        }
+        return rawProxy[domain];
+      },
+      has(_, property: string) {
+        return property in rawProxy;
+      },
+      ownKeys() {
+        return Object.keys(rawProxy);
+      },
+      set() {
+        // lol, no
+        return false;
+      },
+    });
+  }
+
+  return buildCallProxy();
+}

package/src/extensions/config.extension.ts

@@ -0,0 +1,119 @@
+/* eslint-disable @typescript-eslint/no-magic-numbers */
+import {
+  asyncNoop,
+  INCREMENT,
+  is,
+  SECOND,
+  sleep,
+  START,
+  TServiceParams,
+} from "@digital-alchemy/core";
+import { env } from "process";
+
+import {
+  ALL_SERVICE_DOMAINS,
+  HassConfigService,
+  HassServiceDTO,
+  iCallService,
+  PostConfigPriorities,
+} from "..";
+
+const MAX_ATTEMPTS = 50;
+const FAILED = 1;
+
+export const SERVICE_LIST_UPDATED = "SERVICE_LIST_UPDATED";
+
+export function Configure({
+  logger,
+  lifecycle,
+  event,
+  hass,
+  config,
+  internal,
+}: TServiceParams): HassConfigService {
+  lifecycle.onPreInit(() => {
+    // HASSIO_TOKEN provided by home assistant to addons
+    // SUPERVISOR_TOKEN used as alias elsewhere
+    const token = env.HASSIO_TOKEN || env.SUPERVISOR_TOKEN;
+    if (is.empty(token)) {
+      return;
+    }
+    logger.debug({ name: "onPreInit" }, `auto configuring from addon environment`);
+    internal.boilerplate.configuration.set(
+      "hass",
+      "BASE_URL",
+      // don't go over the network
+      env.HASS_SERVER || "http://supervisor/core",
+    );
+    internal.boilerplate.configuration.set("hass", "TOKEN", token);
+  });
+
+  /**
+   * Request by someone to validate the provided credentials are valid
+   *
+   * Send a test request, and provide feedback on what happened
+   */
+  lifecycle.onPostConfig(async () => {
+    if (!config.hass.VALIDATE_CONFIGURATION) {
+      return;
+    }
+    internal.boilerplate.configuration.set("boilerplate", "LOG_LEVEL", "trace");
+    await asyncNoop();
+    logger.info({ name: "onPostConfig" }, `validating credentials`);
+    try {
+      const result = await hass.fetch.checkCredentials();
+      if (is.object(result)) {
+        // * all good
+        logger.info({ name: "onPostConfig" }, result.message);
+        process.exit(1);
+      }
+      // * bad token
+      logger.error({ name: "onPostConfig" }, String(result));
+      process.exit(0);
+    } catch (error) {
+      // * bad BASE_URL
+      logger.error({ error, name: "onPostConfig" }, "failed to send request");
+      process.exit(0);
+    }
+  }, PostConfigPriorities.VALIDATE);
+
+  let services: HassServiceDTO[];
+  async function loadServiceList(recursion = START): Promise<void> {
+    logger.debug({ name: loadServiceList }, `fetching service list`);
+    services = await hass.fetch.listServices();
+    if (is.empty(services)) {
+      if (recursion > MAX_ATTEMPTS) {
+        logger.fatal({ name: loadServiceList }, `failed to load service list from Home Assistant`);
+        process.exit(FAILED);
+      }
+      logger.warn(
+        { name: loadServiceList },
+        "failed to retrieve {service} list. Retrying {%s}/[%s]",
+        recursion,
+        MAX_ATTEMPTS,
+      );
+      await sleep(config.hass.RETRY_INTERVAL * SECOND);
+      await loadServiceList(recursion + INCREMENT);
+    } else {
+      event.emit(SERVICE_LIST_UPDATED, services);
+      checkedServices = new Map();
+    }
+  }
+  let checkedServices = new Map<string, boolean>();
+
+  return {
+    getServices: () => services,
+    isService: <DOMAIN extends ALL_SERVICE_DOMAINS>(
+      domain: DOMAIN,
+      service: string,
+    ): service is Extract<keyof iCallService[DOMAIN], string> => {
+      if (checkedServices.has(service)) {
+        return checkedServices.get(service);
+      }
+      const exists = services.some(i => i.domain === domain && !is.undefined(i.services[service]));
+      checkedServices.set(service, exists);
+      return exists;
+    },
+    loadServiceList,
+  };
+}

package/src/extensions/conversation.extension.ts

@@ -0,0 +1,46 @@
+import { TServiceParams } from "@digital-alchemy/core";
+
+import {
+  EditAliasOptions,
+  HassConversationService,
+  ToggleExpose,
+  UPDATE_REGISTRY,
+} from "../helpers";
+
+export function Conversation({ hass, logger }: TServiceParams): HassConversationService {
+  async function addAlias({ entity, alias }: EditAliasOptions) {
+    const current = await hass.entity.registry.get(entity);
+    if (current?.aliases?.includes(alias)) {
+      logger.debug({ name: entity }, `already has alias {%s}`, alias);
+      return;
+    }
+    await hass.socket.sendMessage({
+      entity_id: entity,
+      type: "config/entity_registry/update",
+    });
+  }
+
+  async function removeAlias({ entity, alias }: EditAliasOptions) {
+    const current = await hass.entity.registry.get(entity);
+    if (!current?.aliases?.includes(alias)) {
+      logger.debug({ name: entity }, `does not have alias {%s}`, alias);
+      return;
+    }
+    await hass.socket.sendMessage({ entity_id: entity, type: UPDATE_REGISTRY });
+  }
+
+  async function setConversational({ entity_ids, assistants, should_expose }: ToggleExpose) {
+    await hass.socket.sendMessage({
+      assistants: [assistants].flat(),
+      entity_ids: [entity_ids].flat(),
+      should_expose,
+      type: UPDATE_REGISTRY,
+    });
+  }
+
+  return {
+    addAlias,
+    removeAlias,
+    setConversational,
+  };
+}

package/src/extensions/device.extension.ts

@@ -0,0 +1,56 @@
+import { debounce, TServiceParams } from "@digital-alchemy/core";
+
+import {
+  DEVICE_REGISTRY_UPDATED,
+  DeviceDetails,
+  EARLY_ON_READY,
+  HassDeviceService,
+} from "../helpers";
+
+export function Device({
+  hass,
+  config,
+  context,
+  logger,
+  lifecycle,
+  event,
+}: TServiceParams): HassDeviceService {
+  hass.socket.onConnect(async () => {
+    let loading = new Promise<void>(async done => {
+      hass.device.current = await hass.device.list();
+      loading = undefined;
+      done();
+    });
+    lifecycle.onReady(async () => loading && (await loading), EARLY_ON_READY);
+    await subscribeUpdates();
+
+    hass.socket.subscribe({
+      context,
+      event_type: "device_registry_updated",
+      async exec() {
+        await debounce(DEVICE_REGISTRY_UPDATED, config.hass.EVENT_DEBOUNCE_MS);
+        hass.device.current = await hass.device.list();
+        logger.debug(`device registry updated`);
+        event.emit(DEVICE_REGISTRY_UPDATED);
+      },
+    });
+  });
+
+  async function subscribeUpdates() {
+    await hass.socket.sendMessage({
+      event_type: "device_registry_updated",
+      type: "subscribe_events",
+    });
+  }
+
+  async function list() {
+    return await hass.socket.sendMessage<DeviceDetails[]>({
+      type: "config/device_registry/list",
+    });
+  }
+
+  return {
+    current: [] as DeviceDetails[],
+    list,
+  };
+}