@digital-alchemy/hass 24.9.4 → 24.10.1

package/src/helpers/fetch/server-log.ts

@@ -0,0 +1,28 @@
+// {
+// 	"0": {
+// 		"name": "homeassistant.util.yaml.loader",
+// 		"message": [
+// 			"mapping values are not allowed here\n  in \"/config/configuration.yaml\", line 71, column 8"
+// 		],
+// 		"level": "ERROR",
+// 		"source": [
+// 			"util/yaml/loader.py",
+// 			127
+// 		],
+// 		"timestamp": 1638118416.470104,
+// 		"exception": "",
+// 		"count": 2,
+// 		"first_occurred": 1638118343.795454
+// 	}
+// }
+
+export interface HomeAssistantServerLogItem {
+  count: number;
+  exception: string;
+  first_occurred: number;
+  level: "ERROR" | "WARNING";
+  message: string[];
+  name: string;
+  source: [string, number];
+  timestamp: number;
+}

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

@@ -0,0 +1,64 @@
+import { TPlatformId } from "../../dynamic";
+import { ALL_DOMAINS } from "../utility.helper";
+
+export interface ServiceListSelectorTarget {
+  domain?: ALL_DOMAINS;
+  integration?: TPlatformId;
+  multiple?: boolean;
+}
+export interface ServiceListSelector {
+  boolean?: null;
+  entity?: ServiceListSelectorTarget;
+  number?: {
+    max: number;
+    min: number;
+    mode?: string;
+    step?: number;
+    unit_of_measurement: string;
+  };
+  object?: null;
+  select?: {
+    options: Record<"label" | "value", string>[] | string[];
+  };
+  text?: null;
+  time?: null;
+}
+
+export interface ServiceListFieldDescription {
+  advanced?: boolean;
+  default?: unknown;
+  description?: string;
+  example?: string | number;
+  name?: string;
+  required?: boolean;
+  selector?: ServiceListSelector;
+}
+
+export type ServiceListEntityTarget = {
+  domain?: ALL_DOMAINS[];
+  integration?: TPlatformId;
+  supported_features?: number[];
+};
+
+export interface ServiceListServiceTarget {
+  device?: { integration?: string };
+  entity?: ServiceListEntityTarget[];
+  integration?: string;
+}
+
+export interface ServiceListField {
+  description?: string;
+  fields: Record<string, ServiceListFieldDescription>;
+  name?: string;
+  target?: ServiceListServiceTarget;
+  response?: ResponseOptional;
+}
+
+export interface ResponseOptional {
+  optional?: boolean;
+}
+
+export interface HassServiceDTO {
+  domain: ALL_DOMAINS;
+  services: Record<string /* via .name */, ServiceListField>;
+}

package/src/helpers/fetch/weather-forecasts.ts

@@ -0,0 +1,86 @@
+// Comes from https://www.home-assistant.io/integrations/weather/#action-weatherget_forecasts
+
+export type WeatherCondition =
+  | "clear-night"
+  | "cloudy"
+  | "fog"
+  | "hail"
+  | "lightning"
+  | "lightning-rainy"
+  | "partlycloudy"
+  | "pouring"
+  | "rainy"
+  | "snowy"
+  | "snowy-rainy"
+  | "sunny"
+  | "windy"
+  | "windy-variant"
+  | "exceptional";
+
+export interface WeatherGetForecasts {
+  /**
+   * Time of the forecasted conditions.
+   * Format is YYYY-MM-DDTHH:mm:ss+zz:zz
+   */
+  datetime: string;
+  /**
+   * Only set for `twice_daily` forecasts
+   */
+  is_daytime: boolean;
+  /**
+   * The apparent (feels-like) temperature in the unit indicated by the `temperature_unite` state attribute.
+   */
+  apparent_temperature: number;
+  /**
+   * The cloud coverage in %.
+   */
+  cloud_coverage: number;
+  /**
+   * The weather condition
+   */
+  condition: WeatherCondition;
+  /**
+   * The dew point temperature in the unit indicated by the `temperature_unite` state attribute.
+   */
+  dew_point: number;
+  /**
+   * The relative humidity in %.
+   */
+  humidity: number;
+  /**
+   * The probability of precipitation in %;
+   */
+  precipitation_probability: number;
+  /**
+   * The precipitation amount in the unit indicated by the `precipitation_unit` state attribute.
+   */
+  precipitation: number;
+  /**
+   * The air pressure in the unit indicated by the `pressure_unit` state attribute.
+   */
+  pressure: number;
+  /**
+   * The temperature in the unit indicated by the `temperature_unite` state attribute. If `templow` is also provided this is the higher temperature.
+   */
+  temperature: number;
+  /**
+   * The lower temperature in the unit indicated by the `temperature_unite` state attribute.
+   */
+  templow: number;
+  /**
+   * The UV index.
+   */
+  uv_index: number;
+  /**
+   * The wind bearing in azimuth angle (degrees) or 1-3 letter cardinal direction
+   */
+  wind_bearing: number | string;
+  /**
+   * The wind gust speed in the unit indicated by the `wind_speed_unit` state attribute.
+   */
+  wind_gust_speed: number;
+  /**
+   * The wind speed in the unit indicated by the `wind_speed_unit` state attribute.
+   */
+  wind_speed: number;
+}

package/src/helpers/fetch.helper.ts

@@ -0,0 +1,328 @@
+import { is, TContext } from "@digital-alchemy/core";
+import { MergeExclusive } from "type-fest";
+
+/**
+ * Defines the types of parameters that can be used in fetch requests.
+ */
+export type FetchParameterTypes = string | boolean | Date | number | Array<string | Date | number>;
+
+/**
+ * Enumerates HTTP methods used in fetch requests.
+ */
+export enum HTTP_METHODS {
+  get = "get",
+  delete = "delete",
+  put = "put",
+  patch = "patch",
+  post = "post",
+}
+
+type NoBodyMethods = "get" | "delete";
+type BodyMethods = "put" | "patch" | "post";
+
+/**
+ * Represents a fetch request with additional properties and body content.
+ */
+export type FetchWith<
+  EXTRA extends Record<never, string> = Record<never, string>,
+  BODY extends TFetchBody = undefined,
+> = Partial<FetchArguments<BODY>> & EXTRA;
+
+export type FetchProcessTypes = boolean | "text" | "json" | "raw" | undefined;
+
+type BaseFetchArguments = {
+  /**
+   * Headers to append
+   */
+  headers?: Record<string, string>;
+  /**
+   * Query params to send
+   */
+  params?: Record<string, FetchParameterTypes>;
+  /**
+   * Built in post-processing
+   *
+   * - true / "json" = attempt to decode as json
+   * - false / "raw" = return the node-fetch response object without processing
+   * - "text" = return result as text, no additional processing
+   *
+   * ? boolean values are deprecated
+   */
+  process?: FetchProcessTypes;
+};
+
+export type MaybeHttpError = {
+  error: string;
+  message: string;
+  statusCode: number;
+};
+
+type BaseFetchUrl = {
+  /**
+   * URL to send request to
+   */
+  url: string;
+} & MergeExclusive<
+  {
+    /**
+     * Frequently filled in by wrapper services
+     */
+    baseUrl?: string;
+  },
+  {
+    /**
+     * URL is the full path (includes http://...)
+     *
+     * Ignores baseUrl if set
+     */
+    rawUrl?: boolean;
+  }
+>;
+
+type BaseFetchBody<BODY extends TFetchBody = undefined> = MergeExclusive<
+  {
+    /**
+     * POSTDATA
+     */
+    body?: BODY;
+    /**
+     * HTTP method
+     */
+    method: BodyMethods;
+  },
+  {
+    /**
+     * HTTP method
+     */
+    method?: NoBodyMethods;
+  }
+>;
+
+/**
+ * Defines the structure and types for arguments passed to fetch requests.
+ */
+export type FetchArguments<BODY extends TFetchBody = undefined> = BaseFetchUrl &
+  BaseFetchArguments &
+  BaseFetchBody<BODY>;
+
+/**
+ * Represents a subset of FetchArguments for specific use cases.
+ */
+export type FilteredFetchArguments<BODY extends TFetchBody = undefined> = BaseFetchBody<BODY> &
+  Pick<BaseFetchUrl, "url"> &
+  Pick<BaseFetchArguments, "process" | "params">;
+
+/**
+ * Same thing as FetchWith, but the function doesn't need any args
+ *
+ * This is a work around, for some reason the default value approach isn't work as I had hoped
+ */
+export type BaseFetch = Partial<FetchArguments>;
+
+/**
+ * Defines the types of values that can be used in filter operations.
+ */
+export type FilterValueType = string | boolean | number | Date | RegExp | Record<string, string>;
+
+/**
+ * Enumerates the types of operations available for data filtering.
+ */
+export enum FILTER_OPERATIONS {
+  // "elemMatch" functionality in mongo
+  // eslint-disable-next-line unicorn/prevent-abbreviations
+  elem = "elem",
+  regex = "regex",
+  in = "in",
+  nin = "nin",
+  lt = "lt",
+  lte = "lte",
+  gt = "gt",
+  gte = "gte",
+  exists = "exists",
+  empty = "empty",
+  ne = "ne",
+  eq = "eq",
+}
+
+export interface ComparisonDTO {
+  operation?: FILTER_OPERATIONS | `${FILTER_OPERATIONS}`;
+  value?: FilterValueType | FilterValueType[];
+}
+
+export interface Filter<FIELDS = string> extends ComparisonDTO {
+  empty?: boolean;
+  exists?: boolean;
+  field?: FIELDS;
+}
+
+export interface ResultControl {
+  filters?: Set<Filter>;
+  limit?: number;
+  select?: string[];
+  skip?: number;
+  sort?: string[];
+}
+
+export function controlToQuery(value: Readonly<ResultControl>): Record<string, string> {
+  const out = new Map<string, string>();
+  if (value?.limit) {
+    out.set("limit", value.limit.toString());
+  }
+  if (value?.skip) {
+    out.set("skip", value.skip.toString());
+  }
+  if (value?.sort) {
+    out.set("sort", value.sort.join(","));
+  }
+  if (value?.select) {
+    out.set("select", value.select.join(","));
+  }
+  value?.filters?.forEach(f => {
+    let field = f.field;
+    if (f.operation && f.operation !== FILTER_OPERATIONS.eq) {
+      field = `${field}__${f.operation}`;
+    }
+    let value = f.value;
+    if (is.array(value)) {
+      value = value.join(",");
+    }
+    if (value instanceof Date) {
+      value = value.toISOString();
+    }
+    if (value === null) {
+      value = "null";
+    }
+    if (field) {
+      out.set(field, String(value) ?? "");
+    }
+  });
+  return Object.fromEntries(out.entries());
+}
+
+export function buildFilter(key: string, value: FilterValueType | FilterValueType[]): Filter {
+  const [name, operation] = key.split("__") as [string, FILTER_OPERATIONS];
+  switch (operation) {
+    case "in":
+    case "nin":
+      if (!is.array(value)) {
+        value = is.string(value) ? value.split(",") : [value];
+      }
+      return {
+        field: name,
+        operation,
+        value: value,
+      };
+    case "elem":
+      return {
+        field: name,
+        operation,
+        value: is.string(value) ? JSON.parse(value) : value,
+      };
+    default:
+      return {
+        field: name,
+        operation,
+        value,
+      };
+  }
+}
+
+export function queryToControl(value: Readonly<Record<string, string>>): ResultControl {
+  const filters = new Set<Filter<string>>();
+  const out: ResultControl = { filters };
+  const parameters = new Map<string, string>(Object.entries(value));
+  parameters.forEach((value, key) => {
+    const [name, operation] = key.split("__") as [string, FILTER_OPERATIONS];
+    switch (key) {
+      case "select":
+        out.select = value.split(",");
+        return;
+      case "sort":
+        out.sort = value.split(",");
+        return;
+      case "limit":
+        out.limit = Number(value);
+        return;
+      case "skip":
+        out.skip = Number(value);
+        return;
+    }
+    switch (operation) {
+      case "in":
+      case "nin":
+        filters.add({
+          field: name,
+          operation,
+          value: value.split(","),
+        });
+        return;
+      case "elem":
+        filters.add({
+          field: name,
+          operation,
+          value: JSON.parse(value),
+        });
+        return;
+      default:
+        filters.add({
+          field: name,
+          operation,
+          value,
+        });
+    }
+  });
+  return out;
+}
+
+/**
+ * Properties that alter the way that fetcher works.
+ */
+export type FetcherOptions = {
+  /**
+   * typically domain names with scheme, added to the front of urls if the individual request doesn't override
+   */
+  baseUrl?: string;
+  /**
+   * merged into every request
+   */
+  headers?: Record<string, string>;
+  /**
+   * Alter the context attached to the log statements emitted from the fetcher
+   */
+  context?: TContext;
+};
+
+export type DownloadOptions<BODY extends TFetchBody = undefined> = Partial<FetchArguments<BODY>> & {
+  destination: string;
+};
+
+export function fetchCast(item: FetchParameterTypes): string {
+  if (is.array(item)) {
+    return item.map(i => fetchCast(i)).join(",");
+  }
+  if (item instanceof Date) {
+    return item.toISOString();
+  }
+  if (is.number(item)) {
+    return item.toString();
+  }
+  if (is.boolean(item)) {
+    return item ? "true" : "false";
+  }
+  return item;
+}
+
+export type TFetchBody = object | undefined;
+
+export function buildFilterString(
+  fetchWith: FetchWith<{
+    filters?: Readonly<ResultControl>;
+    params?: Record<string, FetchParameterTypes>;
+  }>,
+): string {
+  return new URLSearchParams({
+    ...Object.fromEntries(
+      Object.entries(fetchWith.params ?? {}).map(([label, value]) => [label, fetchCast(value)]),
+    ),
+  }).toString();
+}

package/src/helpers/id-by.helper.ts

@@ -0,0 +1,53 @@
+import {
+  TAreaId,
+  TDeviceId,
+  TFloorId,
+  TLabelId,
+  TPlatformId,
+  TRawEntityIds,
+  TUniqueId,
+  TUniqueIDMapping,
+} from "../dynamic";
+import {
+  ALL_DOMAINS,
+  ANY_ENTITY,
+  PICK_ENTITY,
+  PICK_FROM_AREA,
+  PICK_FROM_DEVICE,
+  PICK_FROM_FLOOR,
+  PICK_FROM_LABEL,
+  PICK_FROM_PLATFORM,
+} from "./utility.helper";
+
+export type IDByInterface = {
+  area: <AREA extends TAreaId, DOMAIN extends ALL_DOMAINS>(
+    area: AREA,
+    ...domains: DOMAIN[]
+  ) => PICK_FROM_AREA<AREA, DOMAIN>[];
+  device: <DEVICE extends TDeviceId, DOMAIN extends ALL_DOMAINS>(
+    device: DEVICE,
+    ...domains: DOMAIN[]
+  ) => PICK_FROM_DEVICE<DEVICE, DOMAIN>[];
+  domain: <DOMAIN extends ALL_DOMAINS>(domain: DOMAIN) => PICK_ENTITY<DOMAIN>[];
+  floor: <FLOOR extends TFloorId, DOMAIN extends ALL_DOMAINS>(
+    floor: FLOOR,
+    ...domains: DOMAIN[]
+  ) => PICK_FROM_FLOOR<FLOOR, DOMAIN>[];
+  label: <LABEL extends TLabelId, DOMAIN extends ALL_DOMAINS>(
+    label: LABEL,
+    ...domains: DOMAIN[]
+  ) => PICK_FROM_LABEL<LABEL, DOMAIN>[];
+  platform: <PLATFORM extends TPlatformId, DOMAIN extends ALL_DOMAINS>(
+    platform: PLATFORM,
+    ...domains: DOMAIN[]
+  ) => PICK_FROM_PLATFORM<PLATFORM, DOMAIN>[];
+  unique_id: <
+    UNIQUE_ID extends TUniqueId,
+    ENTITY_ID extends Extract<TUniqueIDMapping[UNIQUE_ID], ANY_ENTITY> = Extract<
+      TUniqueIDMapping[UNIQUE_ID],
+      TRawEntityIds
+    >,
+  >(
+    unique_id: UNIQUE_ID,
+  ) => ENTITY_ID;
+};

package/src/helpers/index.ts

@@ -0,0 +1,13 @@
+export * from "./backup.helper";
+export * from "./constants.helper";
+export * from "./device.helper";
+export * from "./entity-state.helper";
+export * from "./features.helper";
+export * from "./fetch";
+export * from "./fetch.helper";
+export * from "./id-by.helper";
+export * from "./interfaces.helper";
+export * from "./notify.helper";
+export * from "./registry";
+export * from "./utility.helper";
+export * from "./websocket.helper";