@digital-alchemy/hass 24.9.4 → 24.9.5

package/src/helpers/interfaces.helper.ts

@@ -0,0 +1,340 @@
+import { TBlackHole } from "@digital-alchemy/core";
+import EventEmitter from "events";
+import WS from "ws";
+
+import {
+  iCallService,
+  TAreaId,
+  TDeviceId,
+  TFloorId,
+  TLabelId,
+  TPlatformId,
+  TRawDomains,
+  TRawEntityIds,
+  TUniqueId,
+  TUniqueIDMapping,
+} from "../dynamic";
+import { BackupResponse, HomeAssistantBackup } from "./backup.helper";
+import { DeviceDetails } from "./device.helper";
+import { ByIdProxy } from "./entity-state.helper";
+import { AreaCreate, AreaDetails, ConfigEntry, HassConfig, HassServiceDTO } from "./fetch";
+import {
+  EditAliasOptions,
+  EditLabelOptions,
+  EntityRegistryItem,
+  FloorCreate,
+  FloorDetails,
+  LabelDefinition,
+  LabelOptions,
+  ManifestItem,
+  ToggleExpose,
+  UpdateCoreOptions,
+  ZoneDetails,
+  ZoneOptions,
+} from "./registry";
+import {
+  ALL_DOMAINS,
+  ALL_SERVICE_DOMAINS,
+  ANY_ENTITY,
+  ENTITY_STATE,
+  PICK_ENTITY,
+  PICK_FROM_AREA,
+  PICK_FROM_DEVICE,
+  PICK_FROM_FLOOR,
+  PICK_FROM_LABEL,
+  PICK_FROM_PLATFORM,
+} from "./utility.helper";
+import {
+  EntityHistoryDTO,
+  EntityHistoryResult,
+  OnHassEventOptions,
+  SocketMessageDTO,
+  SocketSubscribeOptions,
+} from "./websocket.helper";
+
+export type HassAreaService = {
+  apply: (
+    area: TAreaId,
+    entities: ANY_ENTITY[],
+  ) => Promise<{
+    updated: ANY_ENTITY[];
+  }>;
+  create: (details: AreaCreate) => Promise<void>;
+  current: AreaDetails[];
+  delete: (area_id: TAreaId) => Promise<void>;
+  list: () => Promise<AreaDetails[]>;
+  update: (details: AreaDetails) => Promise<void>;
+};
+
+export type HassZoneService = {
+  create: (options: ZoneOptions) => Promise<void>;
+  current: ZoneDetails[];
+  list: () => Promise<ZoneDetails[]>;
+  update: (zone_id: string, options: ZoneOptions) => Promise<void>;
+};
+
+export type HassLabelService = {
+  create: (details: LabelOptions) => Promise<void>;
+  current: LabelDefinition[];
+  delete: (label_id: TLabelId) => Promise<void>;
+  list: () => Promise<LabelDefinition[]>;
+  update: (details: LabelDefinition) => Promise<void>;
+};
+
+export type HassBackupService = {
+  download: (slug: string, destination: string) => Promise<void>;
+  generate: () => Promise<HomeAssistantBackup>;
+  list: () => Promise<BackupResponse>;
+  remove: (slug: string) => Promise<void>;
+};
+
+export type HassConfigService = {
+  getServices: () => HassServiceDTO[];
+  isService: <DOMAIN extends ALL_SERVICE_DOMAINS>(
+    domain: DOMAIN,
+    service: string,
+  ) => service is Extract<keyof iCallService[DOMAIN], string>;
+  loadServiceList: (recursion?: number) => Promise<void>;
+};
+
+export type HassWebsocketAPI = {
+  /**
+   * @internal
+   */
+  attachScheduledFunctions: () => void;
+  connection: WS;
+  /**
+   * the current state of the websocket
+   */
+  connectionState: ConnectionState;
+  /**
+   * can override as part of unit tests
+   */
+  createConnection: (url: string) => WS;
+  /**
+   * Convenient wrapper for sendMessage
+   */
+  fireEvent: (event_type: string, event_data?: object) => Promise<unknown>;
+  /**
+   * Set up a new websocket connection to home assistant
+   *
+   * This doesn't normally need to be called by applications, the extension self manages
+   */
+  init: () => Promise<void>;
+  /**
+   * run a callback when the socket finishes (re)connecting
+   */
+  onConnect: (callback: () => TBlackHole) => void;
+  /**
+   * Attach to the incoming stream of socket events. Do your own filtering and processing from there
+   *
+   * Returns removal function
+   */
+  onEvent: <DATA extends object>({
+    context,
+    event,
+    once,
+    exec,
+  }: OnHassEventOptions<DATA>) => () => void;
+  /**
+   * @internal
+   *
+   * for unit testing
+   */
+  onMessage: (message: SocketMessageDTO) => Promise<void>;
+  /**
+   * when true:
+   * - outgoing socket messages are blocked
+   * - entities don't emit updates
+   */
+  pauseMessages: boolean;
+  /**
+   * Send a message to home assistant via the socket connection
+   *
+   * Applications probably want a higher level function than this
+   */
+  sendMessage: <RESPONSE_VALUE extends unknown = unknown>(
+    data: {
+      type: string;
+      id?: number;
+      [key: string]: unknown;
+    },
+    waitForResponse?: boolean,
+    subscription?: () => void,
+  ) => Promise<RESPONSE_VALUE>;
+  /**
+   * internal
+   */
+  setConnectionState: (state: ConnectionState) => void;
+  /**
+   * internal
+   */
+  socketEvents: EventEmitter;
+  /**
+   * Subscribe to hass core registry updates.
+   *
+   * Not the same as `onEvent` (you probably want that)
+   */
+  subscribe: <EVENT extends string>({
+    event_type,
+    context,
+    exec,
+  }: SocketSubscribeOptions<EVENT>) => Promise<void>;
+  /**
+   * remove the current socket connection to home assistant
+   *
+   * will need to call init() again to start up
+   */
+  teardown: () => Promise<void>;
+  waitForReply: (id: number, data: object, sentAt: Date) => Promise<void>;
+};
+
+/* eslint-disable @typescript-eslint/no-magic-numbers */
+export enum WebsocketConnectionState {
+  offline = 1,
+  connecting = 2,
+  connected = 3,
+  unknown = 4,
+  invalid = 5,
+}
+/* eslint-enable @typescript-eslint/no-magic-numbers */
+
+export type ConnectionState = `${keyof typeof WebsocketConnectionState}`;
+
+export type HassConversationService = {
+  addAlias: (options: EditAliasOptions) => Promise<void>;
+  removeAlias: (options: EditAliasOptions) => Promise<void>;
+  setConversational: (options: ToggleExpose) => Promise<void>;
+};
+
+export type HassDeviceService = {
+  current: DeviceDetails[];
+  list: () => Promise<DeviceDetails[]>;
+};
+
+export type HassEntityManagerRegistry = {
+  addLabel: ({ entity, label }: EditLabelOptions) => Promise<void>;
+  current: EntityRegistryItem<TRawEntityIds>[];
+  get: <ENTITY extends ANY_ENTITY>(entity_id: ENTITY) => Promise<EntityRegistryItem<ENTITY>>;
+  list: () => Promise<EntityRegistryItem<TRawEntityIds>[]>;
+  registryList: () => Promise<EntityRegistryItem<TRawEntityIds>[]>;
+  removeEntity: (entity_id: ANY_ENTITY | ANY_ENTITY[]) => Promise<void>;
+  removeLabel: ({ entity, label }: EditLabelOptions) => Promise<void>;
+  source: () => Promise<Record<TRawEntityIds, { domain: string }>>;
+};
+
+export type TMasterState = {
+  [DOMAIN in ALL_DOMAINS]: Record<string, ENTITY_STATE<PICK_ENTITY<DOMAIN>>>;
+};
+
+export type HassEntityManager = {
+  /**
+   * Internal library use only
+   */
+  _entityUpdateReceiver: <ENTITY extends ANY_ENTITY = TRawEntityIds>(
+    entity_id: ENTITY,
+    new_state: ENTITY_STATE<ENTITY>,
+    old_state: ENTITY_STATE<ENTITY>,
+  ) => void;
+  _masterState: () => Partial<TMasterState>;
+  /**
+   * Retrieves the current state of a given entity. This method returns
+   * raw data, offering a direct view of the entity's state at a given moment.
+   */
+  getCurrentState: <ENTITY_ID extends ANY_ENTITY>(entity_id: ENTITY_ID) => ENTITY_STATE<ENTITY_ID>;
+  /**
+   * Retrieves the historical state data of entities over a specified time
+   * period. Useful for analysis or tracking changes over time.
+   */
+  history: <ENTITES extends ANY_ENTITY[]>(
+    payload: Omit<EntityHistoryDTO<ENTITES>, "type">,
+  ) => Promise<{
+    [k: string]: EntityHistoryResult[];
+  }>;
+  /**
+   * Provides a simple listing of all entity IDs. Useful for enumeration
+   * and quick reference to all available entities.
+   */
+  listEntities: <DOMAIN extends ALL_DOMAINS = TRawDomains>(
+    domain?: DOMAIN,
+  ) => PICK_ENTITY<DOMAIN>[];
+  /**
+   * Returns the previous entity state (not a proxy)
+   */
+  previousState: (entity_id: ANY_ENTITY) => ENTITY_STATE<TRawEntityIds>;
+  /**
+   * Initiates a refresh of the current entity states. Useful for ensuring
+   * synchronization with the latest state data from Home Assistant.
+   */
+  refresh: (recursion?: number) => Promise<void>;
+  /**
+   * Interact with the entity registry
+   */
+  registry: HassEntityManagerRegistry;
+  /**
+   * @internal
+   */
+  warnEarly: (method: string) => void;
+};
+
+export type SimpleCallback = () => TBlackHole;
+
+export type HassEventsService = {
+  onAreaRegistryUpdate: (callback: SimpleCallback) => void;
+  onDeviceRegistryUpdate: (callback: SimpleCallback) => void;
+  onEntityRegistryUpdate: (callback: SimpleCallback) => void;
+  onFloorRegistryUpdate: (callback: SimpleCallback) => void;
+  onLabelRegistryUpdate: (callback: SimpleCallback) => void;
+  onZoneRegistryUpdate: (callback: SimpleCallback) => void;
+};
+
+export type HassFloorService = {
+  create(details: FloorCreate): Promise<void>;
+  current: FloorDetails[];
+  delete(floor_id: TFloorId): Promise<void>;
+  list(): Promise<FloorDetails[]>;
+  update(details: FloorDetails): Promise<void>;
+};
+
+export type HassReferenceService = {
+  area: <AREA extends TAreaId, DOMAINS extends TRawDomains = TRawDomains>(
+    area: AREA,
+    ...domains: DOMAINS[]
+  ) => ByIdProxy<PICK_FROM_AREA<AREA, DOMAINS>>[];
+  device: <DEVICE extends TDeviceId, DOMAINS extends TRawDomains = TRawDomains>(
+    device: DEVICE,
+    ...domains: DOMAINS[]
+  ) => ByIdProxy<PICK_FROM_DEVICE<DEVICE, DOMAINS>>[];
+  domain: <DOMAIN extends TRawDomains = TRawDomains>(
+    domain: DOMAIN,
+  ) => ByIdProxy<PICK_ENTITY<DOMAIN>>[];
+  floor: <FLOOR extends TFloorId, DOMAINS extends TRawDomains = TRawDomains>(
+    floor: FLOOR,
+    ...domains: DOMAINS[]
+  ) => ByIdProxy<PICK_FROM_FLOOR<FLOOR, DOMAINS>>[];
+  id: <ENTITY_ID extends ANY_ENTITY>(entity_id: ENTITY_ID) => ByIdProxy<ENTITY_ID>;
+  label: <LABEL extends TLabelId, DOMAINS extends TRawDomains = TRawDomains>(
+    label: LABEL,
+    ...domains: DOMAINS[]
+  ) => ByIdProxy<PICK_FROM_LABEL<LABEL, DOMAINS>>[];
+  platform: <PLATFORM extends TPlatformId, DOMAINS extends TRawDomains = TRawDomains>(
+    platform: PLATFORM,
+    ...domains: DOMAINS[]
+  ) => ByIdProxy<PICK_FROM_PLATFORM<PLATFORM, DOMAINS>>[];
+  unique_id: <
+    UNIQUE_ID extends TUniqueId,
+    ENTITY_ID extends Extract<TUniqueIDMapping[UNIQUE_ID], ANY_ENTITY> = Extract<
+      TUniqueIDMapping[UNIQUE_ID],
+      ANY_ENTITY
+    >,
+  >(
+    unique_id: UNIQUE_ID,
+  ) => ByIdProxy<ENTITY_ID>;
+};
+
+export type HassRegistryService = {
+  getConfig: () => Promise<HassConfig>;
+  getConfigEntries: () => Promise<ConfigEntry[]>;
+  manifestList: () => Promise<ManifestItem[]>;
+  updateCore: (options: UpdateCoreOptions) => Promise<void>;
+};

package/src/helpers/notify.helper.ts

@@ -0,0 +1,302 @@
+export type AppleNotificationPush = {
+  /**
+   * **iOS | MacOS**
+   *
+   * The sound to play for the notification.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#sounds)
+   *
+   * > default: "none"
+   */
+  sound?: string;
+
+  /**
+   * **iOS | MacOS**
+   *
+   * The badge number to display on the app icon.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#badge)
+   */
+  badge?: number;
+
+  /**
+   * **iOS | MacOS**
+   *
+   * The interruption level of the notification.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#interruption-level)
+   */
+  interruption_level?: "passive" | "active" | "time-sensitive" | "critical";
+
+  /**
+   * **iOS | MacOS**
+   *
+   * The presentation options for the notification.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#presentation-options)
+   */
+  presentation_options?: ["alert" | "badge" | "sound"];
+};
+
+export type NotificationAction = {
+  /**
+   * Key passed back in events.
+   *
+   * ## REPLY
+   *
+   * When set to `REPLY`, you will be prompted for text to send with the event.
+   *
+   * ## URI
+   *
+   */
+  action: string;
+  /**
+   * Shown on the action button to the user.
+   */
+  title: string;
+  /**
+   * The URI to open when selected.
+   * Android requires setting the action string to `URI` to use this key. [More Info](https://companion.home-assistant.io/docs/notifications/actionable-notifications/#uri-values).
+   */
+  uri?: string;
+};
+
+export type AndroidNotificationActionOptions = Record<string, unknown>;
+
+export type AppleNotificationActionOptions = {
+  /**
+   * **iOS | MacOS**
+   *
+   * Set to `foreground` to launch the app when tapped. Defaults to background which just fires the event.
+   * This is automatically set to foreground when providing a uri.
+   */
+  activationMode?: "foreground" | "background";
+  /**
+   * **iOS | MacOS**
+   *
+   * Set to `true` to require a password to fire the event.
+   */
+  authenticationRequired?: boolean;
+  /**
+   * **iOS | MacOS**
+   *
+   * Set to `true` to color the actions title red.
+   */
+  destructive?: boolean;
+  /**
+   * **iOS | MacOS**
+   *
+   * Set to `textInput` to prompt for text to return with the event. This also occurs when setting the action to `REPLY`.
+   */
+  behavior?: "textInput";
+  /**
+   * **iOS | MacOS**
+   *
+   * Title to use for text input for actions that prompt.
+   */
+  textInputButtonTitle?: string;
+  /**
+   * **iOS | MacOS**
+   *
+   * Placeholder to use for text input for actions that prompt.
+   */
+  textInputPlaceholder?: string;
+  /**
+   * **iOS | MacOS**
+   *
+   * The icon to use for the notification.
+   * * [More info](https://companion.home-assistant.io/docs/notifications/actionable-notifications#icon-values)
+   */
+  icon?: string;
+};
+
+export type AppleNotificationData = {
+  /**
+   * **iOS | MacOS**
+   *
+   * The URL to open when the notification is clicked.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#opening-a-url)
+   */
+  url?: string;
+
+  /**
+   * **iOS | MacOS**
+   *
+   * The subtitle of the notification. Shows under the title.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#subtitle--subject)
+   */
+  subtitle?: string;
+  push?: AppleNotificationPush;
+  /**
+   * iOS Supports ~10 actions.
+   */
+  actions?: Array<NotificationAction & AppleNotificationActionOptions>;
+};
+
+export type AndroidNotificationData = {
+  /**
+   * **Android**
+   *
+   * The action to perform when the notification is clicked.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#opening-a-url)
+   */
+  clickAction?: string;
+
+  /**
+   * **Android**
+   *
+   * The subject of the notification.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#subtitle--subject)
+   */
+  subject?: string;
+
+  /**
+   * **Android**
+   *
+   * The color of the notification.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#notification-color)
+   */
+  color?: string;
+
+  /**
+   * **Android**
+   *
+   * Whether the notification should be sticky (persistent).
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#sticky-notification)
+   */
+  sticky?: boolean;
+
+  /**
+   * **Android**
+   *
+   * The channel to which the notification belongs.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#notification-channels)
+   */
+  channel?: string;
+
+  /**
+   * **Android**
+   *
+   * The importance level of the notification.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#notification-channel-importance)
+   */
+  importance?: "none" | "min" | "low" | "default" | "high" | "max";
+
+  /**
+   * **Android**
+   *
+   * The vibration pattern of the notification.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#notification-vibration-pattern)
+   */
+  vibrationPattern?: string;
+
+  /**
+   * **Android**
+   *
+   * The LED color of the notification.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#notification-led-color)
+   */
+  ledColor?: string;
+
+  /**
+   * **Android**
+   *
+   * Whether the notification should be persistent.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#persistent-notification)
+   */
+  persistent?: boolean;
+
+  /**
+   * **Android**
+   *
+   * The timeout duration of the notification.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#notification-timeout)
+   */
+  timeout?: number;
+
+  /**
+   * **Android**
+   *
+   * The URL of the notification icon.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#notification-icon)
+   */
+  icon_url?: string;
+
+  /**
+   * **Android**
+   *
+   * The visibility of the notification on the lock screen.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#notification-sensitivity--lock-screen-visibility)
+   */
+  visibility?: "public" | "private" | "secret";
+  /**
+   * **Android**
+   *
+   * The text to be spoken by text-to-speech notifications.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#text-to-speech-notifications)
+   */
+  tts_text?: string;
+
+  /**
+   * **Android**
+   *
+   * The media stream to be played by the notification.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#text-to-speech-notifications)
+   */
+  media_stream?: "alarm_stream" | "alarm_stream_max";
+
+  /**
+   * **Android**
+   *
+   * Whether the notification should display a chronometer.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#chronometer-notifications)
+   */
+  chronometer?: boolean;
+
+  /**
+   * **Android**
+   *
+   * The timestamp to display in the notification.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#chronometer-notifications)
+   */
+  when?: number;
+
+  /**
+   * **Android**
+   *
+   * Whether the notification should only alert once.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#alert-once)
+   */
+  alert_once?: boolean;
+
+  /**
+   * **Android**
+   *
+   * The status bar icon of the notification.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#notification-status-bar-icon)
+   */
+  notification_icon?: string;
+
+  /**
+   * **Android**
+   *
+   * Whether the notification should be displayed in the car UI.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#android-auto-visibility)
+   */
+  car_ui?: boolean;
+
+  /**
+   * Android Supports 3 actions.
+   */
+  actions?: Array<NotificationAction & AndroidNotificationActionOptions>;
+};
+
+export type NotificationData = {
+  /**
+   * The group to which the notification belongs.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#grouping)
+   */
+  group?: string;
+
+  /**
+   * The tag to identify the notification for replacement by another.
+   * [More info](https://companion.home-assistant.io/docs/notifications/notifications-basic#replacing)
+   */
+  tag?: string;
+};