@digital-alchemy/hass 0.2.0

package/dist/helpers/metrics.helper.d.ts

@@ -0,0 +1,13 @@
+import { Counter, Summary } from "prom-client";
+/**
+ * Tracks the number of times a socket event callback has been executed.
+ */
+export declare const SOCKET_EVENT_EXECUTION_COUNT: Counter<"event" | "context" | "label">;
+/**
+ * Counts the number of errors occurred during socket event callback executions.
+ */
+export declare const SOCKET_EVENT_ERRORS: Counter<"event" | "context" | "label">;
+/**
+ * Summary for Execution Time
+ */
+export declare const SOCKET_EVENT_EXECUTION_TIME: Summary<"event" | "context" | "label">;

package/dist/helpers/metrics.helper.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SOCKET_EVENT_EXECUTION_TIME = exports.SOCKET_EVENT_ERRORS = exports.SOCKET_EVENT_EXECUTION_COUNT = void 0;
+const prom_client_1 = require("prom-client");
+/**
+ * Tracks the number of times a socket event callback has been executed.
+ */
+exports.SOCKET_EVENT_EXECUTION_COUNT = new prom_client_1.Counter({
+    help: "Counts the number of times a socket event callback has been executed",
+    labelNames: ["context", "label", "event"],
+    name: "digital_alchemy_home_assistant_socket_event_callback_execution_count",
+});
+/**
+ * Counts the number of errors occurred during socket event callback executions.
+ */
+exports.SOCKET_EVENT_ERRORS = new prom_client_1.Counter({
+    help: "Counts the number of errors during socket event callback executions",
+    labelNames: ["context", "label", "event"],
+    name: "digital_alchemy_home_assistant_socket_event_callback_errors",
+});
+/**
+ * Summary for Execution Time
+ */
+exports.SOCKET_EVENT_EXECUTION_TIME = new prom_client_1.Summary({
+    help: "Measures the duration of each socket event callback execution",
+    labelNames: ["context", "label", "event"],
+    name: "digital_alchemy_home_assistant_socket_event_callback_execution_time",
+    percentiles: [0.5, 0.9, 0.99],
+});
+//# sourceMappingURL=metrics.helper.js.map

package/dist/helpers/metrics.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.helper.js","sourceRoot":"","sources":["../../src/helpers/metrics.helper.ts"],"names":[],"mappings":";;;AAAA,6CAA+C;AAE/C;;GAEG;AACU,QAAA,4BAA4B,GAAG,IAAI,qBAAO,CAAC;IACtD,IAAI,EAAE,sEAAsE;IAC5E,UAAU,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAU;IAClD,IAAI,EAAE,sEAAsE;CAC7E,CAAC,CAAC;AAEH;;GAEG;AACU,QAAA,mBAAmB,GAAG,IAAI,qBAAO,CAAC;IAC7C,IAAI,EAAE,qEAAqE;IAC3E,UAAU,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAU;IAClD,IAAI,EAAE,6DAA6D;CACpE,CAAC,CAAC;AAEH;;GAEG;AACU,QAAA,2BAA2B,GAAG,IAAI,qBAAO,CAAC;IACrD,IAAI,EAAE,+DAA+D;IACrE,UAAU,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAU;IAClD,IAAI,EAAE,qEAAqE;IAC3E,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC;CAC9B,CAAC,CAAC"}

package/dist/helpers/utility.helper.d.ts

@@ -0,0 +1,53 @@
+import { TBlackHole } from "@digital-alchemy/core";
+import { Get } from "type-fest";
+import { ENTITY_SETUP, iCallService } from "../dynamic";
+import { HassEntityContext } from ".";
+/**
+ * Pick any valid entity, optionally limiting by domain
+ */
+export type PICK_ENTITY<DOMAIN extends ALL_DOMAINS = ALL_DOMAINS> = {
+    [key in DOMAIN]: `${key}.${keyof (typeof ENTITY_SETUP)[key] & string}`;
+}[DOMAIN];
+/**
+ * Pick any valid entity, 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<SERVICE extends PICK_SERVICE> = Get<iCallService, SERVICE> extends (serviceParams: infer ServiceParams) => TBlackHole ? ServiceParams : never;
+export declare function entity_split(entity: {
+    entity_id: PICK_ENTITY;
+} | PICK_ENTITY): [ALL_DOMAINS, string];
+/**
+ * Extract the domain from an entity with type safety
+ */
+export declare function domain(entity: {
+    entity_id: PICK_ENTITY;
+} | PICK_ENTITY): ALL_DOMAINS;
+/**
+ * Type definitions to match a specific entity.
+ */
+export type ENTITY_STATE<ENTITY_ID extends PICK_ENTITY> = Omit<Get<typeof ENTITY_SETUP, ENTITY_ID>, "state" | "context" | "last_changed" | "last_updated"> & {
+    last_changed: string;
+    last_updated: string;
+    state: string;
+    context: HassEntityContext;
+};
+/**
+ * Union of all domains that contain entities
+ */
+export type ALL_DOMAINS = keyof typeof ENTITY_SETUP;
+/**
+ * Union of all services with callable methods
+ */
+export type ALL_SERVICE_DOMAINS = keyof iCallService;
+export type GetDomain<ENTITY extends PICK_ENTITY> = ENTITY extends `${infer domain}.${string}` ? domain : never;
+declare module "@digital-alchemy/core" {
+    interface IsIt {
+        domain: <DOMAIN extends ALL_DOMAINS>(entity: string, domain: DOMAIN) => entity is PICK_ENTITY<DOMAIN>;
+    }
+}
+export declare const PostConfigPriorities: {
+    readonly FETCH: 1;
+    readonly VALIDATE: 2;
+};

package/dist/helpers/utility.helper.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostConfigPriorities = exports.domain = exports.entity_split = void 0;
+const core_1 = require("@digital-alchemy/core");
+function entity_split(entity) {
+    if (core_1.is.object(entity)) {
+        entity = entity.entity_id;
+    }
+    return entity.split(".");
+}
+exports.entity_split = entity_split;
+/**
+ * Extract the domain from an entity with type safety
+ */
+function domain(entity) {
+    if (core_1.is.object(entity)) {
+        entity = entity.entity_id;
+    }
+    return entity_split(entity).shift();
+}
+exports.domain = domain;
+core_1.is.domain = (entity, domain) => {
+    const [test] = entity.split(".");
+    return test === domain;
+};
+exports.PostConfigPriorities = {
+    FETCH: 1,
+    VALIDATE: 2,
+};
+//# sourceMappingURL=utility.helper.js.map

package/dist/helpers/utility.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utility.helper.js","sourceRoot":"","sources":["../../src/helpers/utility.helper.ts"],"names":[],"mappings":";;;AAAA,gDAAuD;AA6BvD,SAAgB,YAAY,CAC1B,MAAgD;IAEhD,IAAI,SAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QACtB,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC;IAC5B,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAA0B,CAAC;AACpD,CAAC;AAPD,oCAOC;AACD;;GAEG;AACH,SAAgB,MAAM,CACpB,MAAgD;IAEhD,IAAI,SAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QACtB,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC;IAC5B,CAAC;IACD,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC,KAAK,EAAiB,CAAC;AACrD,CAAC;AAPD,wBAOC;AA4BD,SAAE,CAAC,MAAM,GAAG,CACV,MAAc,EACd,MAAc,EACiB,EAAE;IACjC,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,OAAO,IAAI,KAAK,MAAM,CAAC;AACzB,CAAC,CAAC;AAUW,QAAA,oBAAoB,GAAG;IAClC,KAAK,EAAE,CAAC;IACR,QAAQ,EAAE,CAAC;CACH,CAAC"}

package/dist/helpers/websocket.helper.d.ts

@@ -0,0 +1,129 @@
+import { TBlackHole, TContext } from "@digital-alchemy/core";
+import { Dayjs } from "dayjs";
+import { HASSIO_WS_COMMAND, HassSocketMessageTypes } from "./constants.helper";
+import { EntityUpdateEvent } from "./entity-state.helper";
+import { ALL_DOMAINS, ENTITY_STATE, PICK_ENTITY } from "./utility.helper";
+export interface AreaDTO {
+    area_id: string;
+    name: string;
+}
+export interface EntityRegistryItem {
+    area_id: string;
+    config_entry_id: string;
+    device_id: string;
+    disabled_by: string;
+    entity_id: string;
+    icon: string;
+    name: string;
+    platform: string;
+}
+export interface DeviceListItemDTO {
+    area_id: string;
+    config_entries: string[];
+    connections: string[][];
+    disabled_by: null;
+    entry_type: null;
+    id: string;
+    identifiers: string[];
+    manufacturer: string;
+    model: string;
+    name: string;
+    name_by_user: null;
+    sw_version: string;
+    via_device_id: null;
+}
+export interface HassNotificationDTO {
+    created_at: string;
+    message: string;
+    notification_id: string;
+    status: "unread";
+    title: string;
+}
+export interface SignRequestResponse {
+    path: string;
+}
+export interface SocketMessageDTO {
+    error?: Record<string, unknown>;
+    event?: EntityUpdateEvent;
+    id: string;
+    message?: string;
+    result?: Record<string, unknown>;
+    type: HassSocketMessageTypes;
+}
+export interface SendSocketMessageDTO {
+    access_token?: string;
+    disabled_by?: "user";
+    domain?: string;
+    hidden_by?: "user";
+    service?: string;
+    service_data?: unknown;
+    type: HASSIO_WS_COMMAND | `${HASSIO_WS_COMMAND}`;
+}
+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: HASSIO_WS_COMMAND.registry_update;
+}
+export interface RemoveEntityMessageDTO {
+    entity_id: PICK_ENTITY;
+    type: HASSIO_WS_COMMAND.entity_remove;
+}
+export interface FindRelatedDTO {
+    item_id: string;
+    item_type: string;
+    type: HASSIO_WS_COMMAND.search_related;
+}
+export interface RegistryGetDTO {
+    entity_id: string;
+    type: HASSIO_WS_COMMAND.registry_get;
+}
+export interface RenderTemplateDTO {
+    template: string;
+    timeout: number;
+    type: HASSIO_WS_COMMAND.render_template;
+}
+export interface SubscribeTriggerDTO {
+    trigger: Record<string, unknown>;
+    type: HASSIO_WS_COMMAND.subscribe_trigger;
+}
+export interface UnsubscribeEventsDTO {
+    subscription: number;
+    type: HASSIO_WS_COMMAND.unsubscribe_events;
+}
+export interface SignPathDTO {
+    path: string;
+    type: HASSIO_WS_COMMAND.download_backup;
+}
+export interface RemoveBackupDTO {
+    slug: string;
+    type: HASSIO_WS_COMMAND.remove_backup;
+}
+export interface EntityHistoryDTO<ENTITIES extends PICK_ENTITY[] = PICK_ENTITY[]> {
+    end_time: Date | string | Dayjs;
+    entity_ids: ENTITIES;
+    minimal_response?: boolean;
+    no_attributes?: boolean;
+    start_time: Date | string | Dayjs;
+    type: HASSIO_WS_COMMAND.history_during_period;
+}
+export type EntityHistoryResult<ENTITY extends PICK_ENTITY = PICK_ENTITY, ATTRIBUTES extends object = object> = Pick<ENTITY_STATE<ENTITY> & {
+    attributes: ATTRIBUTES;
+}, "attributes" | "state"> & {
+    date: Date;
+};
+export type SOCKET_MESSAGES = {
+    id?: number;
+} & (FindRelatedDTO | RegistryGetDTO | RemoveBackupDTO | RenderTemplateDTO | RemoveEntityMessageDTO | SendSocketMessageDTO | SignPathDTO | SubscribeTriggerDTO | UnsubscribeEventsDTO | UpdateEntityMessageDTO | EntityHistoryDTO);
+export type OnHassEventCallback<T = object> = (event: T) => TBlackHole;
+export type OnHassEventOptions<T = object> = {
+    context: TContext;
+    label?: string;
+    exec: OnHassEventCallback<T>;
+    event: string;
+    once?: boolean;
+};

package/dist/helpers/websocket.helper.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=websocket.helper.js.map

package/dist/helpers/websocket.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.helper.js","sourceRoot":"","sources":["../../src/helpers/websocket.helper.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./dynamic"), exports);
+tslib_1.__exportStar(require("./extensions"), exports);
+tslib_1.__exportStar(require("./hass.module"), exports);
+tslib_1.__exportStar(require("./helpers"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,oDAA0B;AAC1B,uDAA6B;AAC7B,wDAA8B;AAC9B,oDAA0B"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@digital-alchemy/hass",
+  "repository": "https://github.com/Digital-Alchemy-TS/hass",
+  "version": "0.2.0",
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src",
+    "prepublishOnly": "npm run build",
+    "upgrade": "ncu -u; npm i"
+  },
+  "author": {
+    "url": "https://github.com/zoe-codez",
+    "name": "Zoe Codez"
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@digital-alchemy/core": "^0.2.0",
+    "dayjs": "^1.11.10",
+    "prom-client": "^15.1.0",
+    "ws": "^8.16.0"
+  },
+  "devDependencies": {
+    "@cspell/eslint-plugin": "^8.6.0",
+    "@types/figlet": "^1.5.8",
+    "@types/jest": "^29.5.12",
+    "@types/js-yaml": "^4.0.9",
+    "@types/minimist": "^1.2.5",
+    "@types/mute-stream": "^0.0.4",
+    "@types/node": "^20.11.25",
+    "@types/uuid": "^9.0.8",
+    "@types/ws": "^8.5.10",
+    "@typescript-eslint/eslint-plugin": "7.1.1",
+    "@typescript-eslint/parser": "7.1.1",
+    "eslint": "8.57.0",
+    "eslint-config-prettier": "9.1.0",
+    "eslint-plugin-import": "^2.29.1",
+    "eslint-plugin-jsonc": "^2.13.0",
+    "eslint-plugin-no-unsanitized": "^4.0.2",
+    "eslint-plugin-prettier": "^5.1.3",
+    "eslint-plugin-security": "^2.1.1",
+    "eslint-plugin-simple-import-sort": "^12.0.0",
+    "eslint-plugin-sonarjs": "^0.24.0",
+    "eslint-plugin-sort-keys-fix": "^1.1.2",
+    "eslint-plugin-unicorn": "^51.0.1",
+    "jest": "^29.7.0",
+    "jest-environment-node": "^29.7.0",
+    "npm-check-updates": "^16.14.15",
+    "prettier": "^3.2.5",
+    "ts-jest": "^29.1.2",
+    "tsx": "^4.7.1",
+    "type-fest": "^4.12.0",
+    "typescript": "^5.4.2"
+  }
+}