@digital-alchemy/hass 25.8.11 → 25.8.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +66 -53
  2. package/package.json +13 -13
package/README.md CHANGED
@@ -1,40 +1,65 @@
1
- [![stars](https://img.shields.io/github/stars/Digital-Alchemy-TS/hass)](https://github.com/Digital-Alchemy-TS/hass)
2
- ![discord](https://img.shields.io/discord/1219758743848489147?label=Discord&logo=discord)
3
1
  [![codecov](https://codecov.io/gh/Digital-Alchemy-TS/hass/graph/badge.svg?token=LYUQ1FQ71D)](https://codecov.io/gh/Digital-Alchemy-TS/hass)
4
2
  [![version](https://img.shields.io/github/package-json/version/Digital-Alchemy-TS/hass)](https://www.npmjs.com/package/@digital-alchemy/hass)
3
+ [![stars](https://img.shields.io/github/stars/Digital-Alchemy-TS/hass)](https://github.com/Digital-Alchemy-TS/hass)
5
4
 
6
5
  ---
7
6
 
8
- # 🏠 Welcome to `@digital-alchemy/hass`!
7
+ <div align="center">
9
8
 
10
- This repository contains generic extensions for interacting with Home Assistant, including websocket & REST API adapters, entity & event management, backup workflows, and more.
9
+ ![Digital Alchemy](https://raw.githubusercontent.com/Digital-Alchemy-TS/.github/main/profile/github-logo.png)
10
+ ![Digital Alchemy](https://avatars.githubusercontent.com/u/13844975?s=125&v=4)
11
11
 
12
- - [Extended docs](https://docs.digital-alchemy.app)
13
- - [Discord](https://discord.gg/JkZ35Gv97Y)
12
+ </div>
14
13
 
15
- ## ⭐ Features
16
- ### 📝 First-class Editor Experiences
14
+ ## Install
17
15
 
18
- - Did you just typo that entity name?
19
- - Just what services are actually available?
16
+ Add as a dependency, and add to your imports. Nice and easy
20
17
 
21
- Create references to entities that will always reflect their current state. Get details about all the services your setup supports and how to use them, directly in your editor.
18
+ ```bash
19
+ yarn add @digital-alchemy/hass
20
+ yarn add -D @digital-alchemy/type-writer
21
+ ```
22
22
 
23
- ![editor](./docs/editor.png)
23
+ ## Introduction
24
24
 
25
- ### 🌐 Managed Websocket
25
+ `@digital-alchemy/hass` builds off the Digital Alchemy core framework to introduce API bindings for Home Assistant, exposing functionality for event subscriptions, websocket & rest api interactions, and more!
26
26
 
27
- Don't worry about all the complexities of dealing with Home Assistant. Let the library help by handling all the connection logic, keeping track of events for you, formatting requests, and more.
27
+ The library is able to be customized with the [type-writer](https://github.com/Digital-Alchemy-TS/type-writer) script in order to customize the editor experience for your individual Home Assistant instance.
28
+ All services with their parameter inputs are available to call, as well as tools to create long term type safe entity references.
28
29
 
29
- ## Install
30
+ - [📚 Extended docs](https://docs.digital-alchemy.app)
30
31
 
31
- Add as a dependency, and add to your imports. Nice and easy
32
+ ## Configuration
33
+
34
+ ### Connection Details
35
+
36
+ If you are running the code within a Home Assistant addon (ex: Code Server or Code Runner), the library will automatically configure from environment variables.
37
+
38
+ All other environments should define credentials in a `.env` file or provide them via environment variables -
39
+
40
+ ```
41
+ HASS_BASE_URL=http://localhost:8123
42
+ HASS_TOKEN=<long lived access token>
43
+ ```
44
+
45
+ ### Customizing Types
46
+
47
+ The `type-writer` script utilizes `hass` under the hood, and will load configuration from the same sources.
48
+ In order to run the script, execute this command from repository root
32
49
 
33
50
  ```bash
34
- npm i @digital-alchemy/hass
51
+ npx type-writer
35
52
  ```
36
53
 
37
- **Add to code**
54
+ This will create / update the `src/hass` folder inside your project with the latest type definitions for your project.
55
+ These have **NO EFFECT** on the way your app performs at runtime, and can be updated as frequently as you like.
56
+
57
+ ## Usage
58
+
59
+ ### Load
60
+
61
+ Once credentials are set and you have your type definitions generated, you can add the library to your existing project
62
+
38
63
  ```typescript
39
64
  import { LIB_HASS } from "@digital-alchemy/hass";
40
65
 
@@ -42,56 +67,44 @@ import { LIB_HASS } from "@digital-alchemy/hass";
42
67
  const MY_APP = CreateApplication({
43
68
  libraries: [LIB_HASS],
44
69
  name: "home_automation",
45
- })
70
+ });
46
71
 
47
72
  // library
48
73
  export const MY_LIBRARY = CreateLibrary({
49
74
  depends: [LIB_HASS],
50
75
  name: "special_logic",
51
- })
76
+ });
52
77
  ```
53
78
 
54
- ## ⚙️ Configuration
55
- ### 🛠 Custom Types
79
+ ### Build logic
56
80
 
57
- This library has support for customizing type definitions to match a particular Home Assistant install. This functionality requires the [type-writer](https://github.com/Digital-Alchemy-TS/type-writer) command to be installed as well.
81
+ The `hass` property will be available via `TServiceParams` in your code
58
82
 
59
- > Add to `devDependencies`!
60
- ```bash
61
- npm i --save-dev @digital-alchemy/type-writer
62
- npx type-writer
63
- ```
64
- Custom types only affect the development experience and have no impact on the way the application runs.
83
+ ```typescript
84
+ import { TServiceParams } from "@digital-alchemy/core";
65
85
 
66
- ### 📦 Supervised Support
86
+ // now available here vvvv
87
+ export function ExampleService({ hass, logger }: TServiceParams) {
88
+ const mySwitch = hass.refBy.id("switch.my_switch");
67
89
 
68
- If your code is running within a Home Assistant addon environment, it will automatically connect with no additional configuration needed.
90
+ // utilize event patterns to trigger logic
91
+ hass.refBy.id("binary_sensor.recent_activity_detected").onUpdate((new_state, old_state) => {
69
92
 
70
- ### 🖥 Manual
93
+ // quickly make logic tests
94
+ if (new_state.state === "on" && mySwitch.state === "off") {
71
95
 
72
- For code running elsewhere, manual configuration is required. You will need a **Long Lived Access Token**, which can be generated on your user profile. You can store your config at `./.{app_name}` or `~/.config/{app_name}` in **INI** format.
96
+ // execute service calls via entities
97
+ mySwitch.turn_on();
73
98
 
74
- > Don't forget to configure "`type_writer`" also!
99
+ } else {
100
+ // get type safe access to the full list of services available on your instance
101
+ hass.call.switch.turn_off({ area: "living_room" });
75
102
 
76
- ```ini
77
- [hass]
78
- BASE_URL=http://localhost:8123
79
- TOKEN=YOUR LONG LIVED ACCESS TOKEN
103
+ }
104
+ });
105
+ }
80
106
  ```
81
107
 
82
- ### 🤖 Unit Testing
83
-
84
- Built in workflows for unit testing using standard test runners like Jest.
85
-
86
- - [Read more](https://docs.digital-alchemy.app/hass/unit-testing)
87
-
88
- ## 🤝 Related Projects
89
-
90
- For additional projects that build on and consume this library, check out these other projects:
108
+ ## Questions / Issues?
91
109
 
92
- | GitHub | Description | NPM |
93
- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
94
- | [synapse](https://github.com/Digital-Alchemy-TS/synapse) | Tools for generating entities within Home Assistant. | [@digitial-alchemy/synapse](https://www.npmjs.com/package/@digital-alchemy/synapse) |
95
- | [automation](https://github.com/Digital-Alchemy-TS/automation) | Advanced automation tools for creating dynamic workflows. | [@digital-alchemy/automation](https://www.npmjs.com/package/@digital-alchemy/automation) |
96
- | [type-writer](https://github.com/Digital-Alchemy-TS/type-writer) | Generate custom type definitions for your setup. | [@digital-alchemy/type-writer](https://www.npmjs.com/package/@digital-alchemy/terminal) |
97
- | [automation-template](https://github.com/Digital-Alchemy-TS/automation-quickstart) | Start your own Home Automation project with the `@digital-alchemy` quick start template | |
110
+ [![discord](https://img.shields.io/discord/1219758743848489147?label=Discord&logo=discord)](https://discord.gg/JkZ35Gv97Y)
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "name": "@digital-alchemy/hass",
4
4
  "repository": "https://github.com/Digital-Alchemy-TS/hass",
5
5
  "homepage": "https://docs.digital-alchemy.app",
6
- "version": "25.8.11",
6
+ "version": "25.8.21",
7
7
  "description": "Typescript APIs for Home Assistant. Includes rest & websocket bindings",
8
8
  "scripts": {
9
9
  "build": "rm -rf dist/; tsc",
@@ -59,20 +59,20 @@
59
59
  "license": "MIT",
60
60
  "devDependencies": {
61
61
  "@cspell/eslint-plugin": "^9.2.0",
62
- "@digital-alchemy/core": "^25.7.1",
63
- "@digital-alchemy/synapse": "^25.3.1",
64
- "@digital-alchemy/type-writer": "^25.6.2",
65
- "@eslint/compat": "^1.3.1",
62
+ "@digital-alchemy/core": "^25.8.21",
63
+ "@digital-alchemy/synapse": "^25.8.11",
64
+ "@digital-alchemy/type-writer": "^25.7.26",
65
+ "@eslint/compat": "^1.3.2",
66
66
  "@eslint/eslintrc": "^3.3.1",
67
- "@eslint/js": "^9.32.0",
67
+ "@eslint/js": "^9.33.0",
68
68
  "@faker-js/faker": "^9.9.0",
69
69
  "@types/js-yaml": "^4.0.9",
70
- "@types/node": "^24.1.0",
70
+ "@types/node": "^24.3.0",
71
71
  "@types/node-cron": "^3.0.11",
72
72
  "@types/semver": "^7.7.0",
73
73
  "@types/ws": "^8.18.1",
74
- "@typescript-eslint/eslint-plugin": "8.39.0",
75
- "@typescript-eslint/parser": "8.39.0",
74
+ "@typescript-eslint/eslint-plugin": "8.40.0",
75
+ "@typescript-eslint/parser": "8.40.0",
76
76
  "@vitest/coverage-v8": "^3.2.4",
77
77
  "dayjs": "^1.11.13",
78
78
  "dotenv": "^17.2.1",
@@ -81,7 +81,7 @@
81
81
  "eslint-plugin-import": "^2.32.0",
82
82
  "eslint-plugin-jsonc": "^2.20.1",
83
83
  "eslint-plugin-no-unsanitized": "^4.1.2",
84
- "eslint-plugin-prettier": "^5.5.3",
84
+ "eslint-plugin-prettier": "^5.5.4",
85
85
  "eslint-plugin-security": "^3.0.1",
86
86
  "eslint-plugin-simple-import-sort": "^12.1.1",
87
87
  "eslint-plugin-sonarjs": "^3.0.4",
@@ -90,8 +90,8 @@
90
90
  "node-cron": "^4.2.1",
91
91
  "prettier": "^3.6.2",
92
92
  "semver": "^7.7.2",
93
- "tsx": "^4.20.3",
94
- "typescript": "^5.8.3",
93
+ "tsx": "^4.20.4",
94
+ "typescript": "^5.9.2",
95
95
  "uuid": "^11.1.0",
96
96
  "vitest": "^3.2.4",
97
97
  "ws": "^8.18.3"
@@ -106,5 +106,5 @@
106
106
  "uuid": "^11.1.0",
107
107
  "ws": "^8.18.3"
108
108
  },
109
- "packageManager": "yarn@4.9.2"
109
+ "packageManager": "yarn@4.9.3"
110
110
  }