@shepherdjerred/home-assistant 0.1.0-dev.14474

package/README.md

@@ -0,0 +1,126 @@
+# @shepherdjerred/home-assistant
+
+Type-safe access to the [Home Assistant](https://www.home-assistant.io/) REST
+and WebSocket APIs for Node.js and Bun. It validates wire data with Zod and can
+generate a schema for one Home Assistant instance, so entity IDs, services, and
+event types are checked before deployment.
+
+Requires Node.js 24 or newer, or Bun.
+
+## Why use this?
+
+Home Assistant integrations tend to put entity IDs, service names, and payloads
+in string literals. Those mistakes otherwise appear only when an automation
+reaches a real home. This package validates API responses at runtime and can
+generate a schema from one instance, moving those mistakes into the editor and
+TypeScript before deployment.
+
+Use it when you are building:
+
+- A Node.js service that reads states or calls services with explicit error
+  types for API, authentication, and WebSocket failures.
+- A typed automation codebase where `light.kitchen`, `light.turn_on`, and its
+  payload must match the Home Assistant instance it will control.
+- A real-time integration that subscribes to Home Assistant events over the
+  WebSocket API instead of polling REST endpoints.
+
+## Quick start
+
+Install the package and provide a Home Assistant long-lived access token through
+your environment:
+
+```bash
+bun add @shepherdjerred/home-assistant
+```
+
+```ts
+import { HomeAssistantRestClient } from "@shepherdjerred/home-assistant";
+
+const { HA_TOKEN: token, HA_URL: baseUrl } = process.env;
+if (baseUrl === undefined || token === undefined) {
+  throw new Error("Set HA_URL and HA_TOKEN before running this program.");
+}
+
+const client = new HomeAssistantRestClient({
+  baseUrl,
+  token,
+});
+
+const state = await client.getState("light.kitchen");
+console.log(state.state);
+
+await client.callService("light", "turn_on", {
+  entity_id: "light.kitchen",
+  brightness: 200,
+});
+```
+
+The runnable [`examples/basic-client.mjs`](examples/basic-client.mjs) requires
+`HA_URL`, `HA_TOKEN`, and `HA_ENTITY_ID`; it never prints the token.
+
+## Generate an instance schema
+
+`ha-codegen` reads Home Assistant's states, services, events, and configuration
+endpoints, then writes a TypeScript module that describes that instance.
+
+```bash
+ha-codegen \
+  --url "$HA_URL" \
+  --out src/generated/ha-schema.ts \
+  --name MyHomeSchema
+```
+
+Do not pass credentials on the command line. The generated module includes
+private entity IDs and service metadata, so add it to `.gitignore` and
+regenerate it when your instance changes.
+
+Use the generated schema as the client type parameter:
+
+```ts
+import { HomeAssistantRestClient } from "@shepherdjerred/home-assistant";
+import type { MyHomeSchema } from "./generated/ha-schema.js";
+
+const { HA_TOKEN: token, HA_URL: baseUrl } = process.env;
+if (baseUrl === undefined || token === undefined) {
+  throw new Error("Set HA_URL and HA_TOKEN before running this program.");
+}
+
+const client = new HomeAssistantRestClient<MyHomeSchema>({
+  baseUrl,
+  token,
+});
+```
+
+## API reference
+
+- `HomeAssistantRestClient` reads state and calls REST services.
+- `HomeAssistantEventClient` connects to the WebSocket API and supports event
+  subscriptions, triggers, service calls, and state reads.
+- `HaApiError`, `HaAuthError`, and `HaWebSocketError` distinguish API,
+  authentication, and socket failures.
+- `ha-codegen --help` lists the command's supported options.
+
+Both clients use the runtime's standard `fetch` and `WebSocket` implementations;
+there is no Bun-only runtime dependency.
+
+## Demo recording
+
+The package includes a replayable asciicast generated from a synthetic local
+Home Assistant API fixture—no live instance data or credentials are recorded.
+It walks from the API data through the generated module to the compile-time
+checks that catch an invalid entity, domain, service, or payload:
+
+```bash
+asciinema play node_modules/@shepherdjerred/home-assistant/demos/codegen-fixture.cast
+```
+
+## Security and compatibility
+
+Use a dedicated long-lived token with only the access your integration needs.
+Keep `HA_TOKEN` in your environment or secret manager, never in shell history,
+source code, or a generated schema. The package targets Node.js 24+ and Bun;
+earlier Node versions are not supported.
+
+## License
+
+GPL-3.0-only.

package/demos/codegen-fixture.cast

@@ -0,0 +1,40 @@
+{"version":3,"term":{"cols":100,"rows":28},"timestamp":1788642698,"idle_time_limit":12.0,"command":"./demos/record-codegen-demo.sh","title":"Home Assistant: API data to compiler-checked client","env":{"SHELL":"/opt/homebrew/bin/fish"}}
+[0.016, "o", "\u001b[2J\u001b[H\u001b[1;36m━━━ Home Assistant -> a typed client ━━━\u001b[0m\r\n\r\n"]
+[2.010, "o", "\u001b[2J\u001b[H\u001b[1;36m━━━ 1/4  Start with runtime API data ━━━\u001b[0m\r\nEntity IDs, service fields, and events begin as JSON from Home Assistant.\r\n"]
+[5.018, "o", "\u001b[2m$ jq -C <selected fields> demos/home-assistant-fixture.json\u001b[0m\r\n\u001b[0;34m{\u001b[0m\r\n  \u001b[1;35m\"entity_id\"\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0;32m\"light.demo_lamp\"\u001b[0m\u001b[0;34m,\u001b[0m\r\n  \u001b[1;35m\"state\"\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0;32m\"off\"\u001b[0m\u001b[0;34m,\u001b[0m\r\n  \u001b[1;35m\"service\"\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0;32m\"light.turn_on\"\u001b[0m\u001b[0;34m,\u001b[0m\r\n  \u001b[1;35m\"field\"\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0;34m{\u001b[0m\r\n    \u001b[1;35m\"brightness\"\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0;32m\"number (optional)\"\u001b[0m\r\n  \u001b[0;34m}\u001b[0m\u001b[0;34m,\u001b[0m\r\n  \u001b[1;35m\"event\"\u001b[0m\u001b[0;34m:\u001b[0m \u001b[0;32m\"state_changed\"\u001b[0m\r\n\u001b[0;34m}\u001b[0m\r\n"]
+[4.008, "o", "\u001b[2J\u001b[H\u001b[1;36m━━━ 2/4  Generate the instance schema ━━━\u001b[0m\r\nha-codegen reads that API and emits a normal TypeScript module.\r\n"]
+[4.008, "o", "\u001b[2m$ node examples/codegen-fixture.mjs | bat --language ts\u001b[0m\r\n"]
+[0.161, "o", "\u001b[38;2;136;57;239mexport\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;136;57;239mconst\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mentities\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;23;146;153m=\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;124;127;147m{\u001b[0m\r\n"]
+[0.000, "o", "\u001b[38;2;76;79;105m  \u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;64;160;43mlight.demo_lamp\u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;23;146;153m:\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;124;127;147m{\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mdomain\u001b[0m\u001b[38;2;23;146;153m:\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;64;160;43mlight\u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;124;127;147m,\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mattributes\u001b[0m\u001b[38;2;23;146;153m:\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;124;127;147m{\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;64;160;43mfriendly_name\u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;23;146;153m:\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;124;127;147m}\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;124;127;147m}\u001b[0m\u001b[38;2;124;127;147m,\u001b[0m\r\n"]
+[0.001, "o", "\u001b[38;2;124;127;147m}\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;136;57;239mas\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;136;57;239mconst\u001b[0m\u001b[38;2;124;127;147m;\u001b[0m\r\n\r\n"]
+[0.001, "o", "\u001b[38;2;136;57;239mexport\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;136;57;239mconst\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mservices\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;23;146;153m=\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;124;127;147m{\u001b[0m\r\n"]
+[0.000, "o", "\u001b[38;2;76;79;105m  \u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;64;160;43mlight\u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;23;146;153m:\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;124;127;147m{\u001b[0m\r\n"]
+[0.000, "o", "\u001b[38;2;76;79;105m    \u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;64;160;43mturn_on\u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;23;146;153m:\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;124;127;147m{\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mfields\u001b[0m\u001b[38;2;23;146;153m:\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;124;127;147m{\u001b[0m\r\n"]
+[0.000, "o", "\u001b[38;2;76;79;105m      \u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;64;160;43mbrightness\u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;23;146;153m:\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;124;127;147m{\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mtype\u001b[0m\u001b[38;2;23;146;153m:\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;64;160;43mnumber\u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;124;127;147m,\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mrequired\u001b[0m\u001b[38;2;23;146;153m:\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;254;100;11mfalse\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;124;127;147m}\u001b[0m\r\n"]
+[0.000, "o", "\u001b[38;2;76;79;105m    \u001b[0m\u001b[38;2;124;127;147m}\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;124;127;147m}\u001b[0m\u001b[38;2;124;127;147m,\u001b[0m\r\n\u001b[38;2;76;79;105m  \u001b[0m\u001b[38;2;124;127;147m}\u001b[0m\u001b[38;2;124;127;147m,\u001b[0m\r\n"]
+[0.000, "o", "\u001b[38;2;124;127;147m}\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;136;57;239mas\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;136;57;239mconst\u001b[0m\u001b[38;2;124;127;147m;\u001b[0m\r\n"]
+[0.000, "o", "\r\n"]
+[0.000, "o", "\u001b[38;2;136;57;239mexport\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;136;57;239mconst\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mevents\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;23;146;153m=\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105m[\u001b[0m\r\n"]
+[0.000, "o", "\u001b[38;2;76;79;105m  \u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;64;160;43mstate_changed\u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;124;127;147m,\u001b[0m\r\n"]
+[0.000, "o", "\u001b[38;2;76;79;105m]\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;136;57;239mas\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;136;57;239mconst\u001b[0m\u001b[38;2;124;127;147m;\u001b[0m\r\n\r\n"]
+[0.001, "o", "\u001b[38;2;136;57;239mexport\u001b[0m\u001b[38;2;223;142;29m \u001b[0m\u001b[38;2;136;57;239mtype\u001b[0m\u001b[38;2;223;142;29m \u001b[0m\u001b[38;2;223;142;29mEventData\u001b[0m\u001b[38;2;223;142;29m \u001b[0m\u001b[38;2;23;146;153m=\u001b[0m\u001b[38;2;223;142;29m \u001b[0m\u001b[38;2;124;127;147m{\u001b[0m\r\n"]
+[0.001, "o", "\u001b[38;2;223;142;29m  \u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;64;160;43mstate_changed\u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;23;146;153m:\u001b[0m\u001b[38;2;223;142;29m \u001b[0m\u001b[38;2;124;127;147m{\u001b[0m\u001b[38;2;223;142;29m \u001b[0m\u001b[38;2;76;79;105mentity_id\u001b[0m\u001b[38;2;23;146;153m:\u001b[0m\u001b[38;2;223;142;29m \u001b[0m\u001b[38;2;136;57;239mstring\u001b[0m\u001b[38;2;124;127;147m;\u001b[0m\u001b[38;2;223;142;29m \u001b[0m\u001b[38;2;76;79;105mold_state\u001b[0m\u001b[38;2;23;146;153m:\u001b[0m\u001b[38;2;223;142;29m \u001b[0m\u001b[38;2;136;57;239munknown\u001b[0m\u001b[38;2;124;127;147m;\u001b[0m\u001b[38;2;223;142;29m \u001b[0m\u001b[38;2;76;79;105mnew_state\u001b[0m\u001b[38;2;23;146;153m:\u001b[0m\u001b[38;2;223;142;29m \u001b[0m\u001b[38;2;136;57;239munknown\u001b[0m\u001b[38;2;223;142;29m \u001b[0m\u001b[38;2;124;127;147m}\u001b[0m\u001b[38;2;124;127;147m;\u001b[0m\r\n"]
+[0.000, "o", "\u001b[38;2;124;127;147m}\u001b[0m\u001b[38;2;124;127;147m;\u001b[0m\r\n"]
+[12.012, "o", "\u001b[2J\u001b[H\u001b[1;36m━━━ 3/4  See the compiler reject a mistyped entity ━━━\u001b[0m\r\nThis temporary client imports the emitted HaSchema and deliberately misspells the entity ID.\r\n"]
+[6.141, "o", "\u001b[2m$ bat invalid.ts\u001b[0m\r\n"]
+[0.019, "o", "\u001b[38;2;136;57;239mimport\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;136;57;239mtype\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;124;127;147m{\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mHomeAssistantRestClient\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;124;127;147m}\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;136;57;239mfrom\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;64;160;43m<package>/dist/index.js\u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;124;127;147m;\u001b[0m\r\n"]
+[0.000, "o", "\u001b[38;2;136;57;239mimport\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;136;57;239mtype\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;124;127;147m{\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mHaSchema\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;124;127;147m}\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;136;57;239mfrom\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;64;160;43m./ha-schema.js\u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;124;127;147m;\u001b[0m\r\n"]
+[0.000, "o", "\r\n"]
+[0.002, "o", "\u001b[38;2;136;57;239mdeclare\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;136;57;239mconst\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mclient\u001b[0m\u001b[38;2;23;146;153m:\u001b[0m\u001b[38;2;223;142;29m \u001b[0m\u001b[38;2;223;142;29mHomeAssistantRestClient\u001b[0m\u001b[38;2;4;165;229m<\u001b[0m\u001b[38;2;223;142;29mHaSchema\u001b[0m\u001b[38;2;4;165;229m>\u001b[0m\u001b[38;2;124;127;147m;\u001b[0m\r\n"]
+[0.000, "o", "\u001b[38;2;76;79;105mclient\u001b[0m\u001b[38;2;23;146;153m.\u001b[0m\u001b[38;2;30;102;245mgetState\u001b[0m\u001b[38;2;76;79;105m(\u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;64;160;43mlight.demo_lmp\u001b[0m\u001b[38;2;64;160;43m\"\u001b[0m\u001b[38;2;76;79;105m)\u001b[0m\u001b[38;2;124;127;147m;\u001b[0m\r\n"]
+[5.012, "o", "\u001b[2m$ tsc --noEmit invalid.ts\u001b[0m\r\n"]
+[0.260, "o", "\u001b[38;2;76;79;105minvalid\u001b[0m\u001b[38;2;23;146;153m.\u001b[0m\u001b[38;2;30;102;245mts\u001b[0m\u001b[38;2;76;79;105m(\u001b[0m\u001b[38;2;254;100;11m5\u001b[0m\u001b[38;2;124;127;147m,\u001b[0m\u001b[38;2;254;100;11m17\u001b[0m\u001b[38;2;76;79;105m)\u001b[0m\u001b[38;2;76;79;105m: \u001b[0m\u001b[38;2;76;79;105merror\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;23;146;153mTS2345\u001b[0m\u001b[38;2;124;127;147m:\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mArgument\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;136;57;239mof\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mtype\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;64;160;43m'\u001b[0m\u001b[38;2;64;160;43m\"light.demo_lmp\"\u001b[0m\u001b[38;2;64;160;43m'\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mis\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mnot\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105massignable\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mto\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mparameter\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;136;57;239mof\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;76;79;105mtype\u001b[0m\u001b[38;2;76;79;105m \u001b[0m\u001b[38;2;64;160;43m'\u001b[0m\u001b[38;2;64;160;43m\"light.demo_lamp\"\u001b[0m\u001b[38;2;64;160;43m'\u001b[0m\u001b[38;2;23;146;153m.\u001b[0m\r\n"]
+[4.011, "o", "\u001b[2J\u001b[H\u001b[1;36m━━━ 4/4  Correct the entity before the request runs ━━━\u001b[0m\r\nThe generated schema gives the editor and CI the same precise feedback.\r\n"]
+[5.009, "o", "\u001b[2m$ delta --color-only --paging never\u001b[0m\r\n"]
+[0.016, "o", "diff --git a/client.ts b/client.ts\r\n--- a/client.ts\r\n+++ b/client.ts\r\n"]
+[0.001, "o", "@@ -3,3 +3,3 @@\r\n"]
+[0.007, "o", "\u001b[2m declare const client: HomeAssistantRestClient<HaSchema>;\u001b[0m\r\n"]
+[0.000, "o", "\u001b[1;31m-client.getState(\"light.demo_lmp\");\u001b[0m\r\n\u001b[1;32m+client.getState(\"light.demo_lamp\");\u001b[0m\r\n\u001b[2m \u001b[0m\r\n"]
+[0.000, "o", "\u001b[1;31m-// The typo would become a failing API request.\u001b[0m\r\n\u001b[1;32m+// The typo is corrected before the request can run.\u001b[0m\r\n"]
+[10.013, "o", "\r\n\u001b[1;32m✓ The generated schema catches the typo before runtime.\u001b[0m\r\n"]
+[0.003, "x", "0"]

package/demos/home-assistant-fixture.json

@@ -0,0 +1,33 @@
+{
+  "states": [
+    {
+      "entity_id": "light.demo_lamp",
+      "state": "off",
+      "attributes": {
+        "friendly_name": "Demo lamp"
+      }
+    }
+  ],
+  "services": [
+    {
+      "domain": "light",
+      "services": {
+        "turn_on": {
+          "fields": {
+            "brightness": {
+              "required": false,
+              "selector": {
+                "number": {}
+              }
+            }
+          }
+        }
+      }
+    }
+  ],
+  "events": [
+    {
+      "event": "state_changed"
+    }
+  ]
+}

package/demos/record-codegen-demo.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+pause_for() {
+  word_count="$(printf '%s' "$1" | wc -w | tr -d '[:space:]')"
+  seconds=$(((word_count + 3) / 4))
+
+  if ((seconds < 2)); then
+    seconds=2
+  elif ((seconds > 12)); then
+    seconds=12
+  fi
+
+  sleep "$seconds"
+}
+
+section() {
+  printf '\033[2J\033[H\033[1;36m━━━ %s ━━━\033[0m\n%s\n' "$1" "$2"
+  pause_for "$1 $2"
+}
+
+section \
+  "Home Assistant -> a typed client" \
+  ""
+
+section \
+  "1/4  Start with runtime API data" \
+  "Entity IDs, service fields, and events begin as JSON from Home Assistant."
+fixture_summary="$(jq -C '{
+  entity_id: .states[0].entity_id,
+  state: .states[0].state,
+  service: "light.turn_on",
+  field: { brightness: "number (optional)" },
+  event: .events[0].event
+}' demos/home-assistant-fixture.json)"
+printf '\033[2m$ jq -C <selected fields> demos/home-assistant-fixture.json\033[0m\n%s\n' "$fixture_summary"
+pause_for "$fixture_summary"
+
+section \
+  "2/4  Generate the instance schema" \
+  "ha-codegen reads that API and emits a normal TypeScript module."
+printf '\033[2m$ node examples/codegen-fixture.mjs | bat --language ts\033[0m\n'
+generated_schema_preview="$(node examples/codegen-fixture.mjs | sed -n '6,25p')"
+printf '%s\n' "$generated_schema_preview" \
+  | bat --color=always --language=typescript --paging=never --plain --style=numbers \
+    --line-range 1:20
+pause_for "$generated_schema_preview"
+
+section \
+  "3/4  See the compiler reject a mistyped entity" \
+  "This temporary client imports the emitted HaSchema and deliberately misspells the entity ID."
+demo_directory="$(mktemp -d -t home-assistant-demo)"
+trap 'rm -r -- "$demo_directory"' EXIT
+package_directory="$(pwd)"
+generated_schema="$demo_directory/ha-schema.ts"
+invalid_client="$demo_directory/invalid.ts"
+diagnostics="$demo_directory/diagnostics.txt"
+node examples/codegen-fixture.mjs >"$generated_schema"
+printf '%s\n' \
+  "import type { HomeAssistantRestClient } from \"${package_directory}/dist/index.js\";" \
+  'import type { HaSchema } from "./ha-schema.js";' \
+  '' \
+  'declare const client: HomeAssistantRestClient<HaSchema>;' \
+  'client.getState("light.demo_lmp");' \
+  >"$invalid_client"
+printf '\033[2m$ bat invalid.ts\033[0m\n'
+invalid_client_preview="$(sed "s#${package_directory}#<package>#g" "$invalid_client")"
+printf '%s\n' "$invalid_client_preview" \
+  | bat --color=always --language=typescript --paging=never --plain --style=numbers
+pause_for "$invalid_client_preview"
+printf '\033[2m$ tsc --noEmit invalid.ts\033[0m\n'
+if (
+  cd "$demo_directory"
+  PATH="$package_directory/node_modules/@typescript/native/bin:$PATH" tsc \
+    --noEmit \
+    --ignoreConfig \
+    --strict \
+    --module NodeNext \
+    --moduleResolution NodeNext \
+    --target ES2024 \
+    invalid.ts
+) >"$diagnostics" 2>&1; then
+  printf '\033[1;31mExpected the invalid entity ID to fail type checking.\033[0m\n' >&2
+  exit 1
+fi
+diagnostic_preview="$(<"$diagnostics")"
+printf '%s\n' "$diagnostic_preview" \
+  | bat --color=always --language=typescript --paging=never --plain --style=numbers
+pause_for "$diagnostic_preview"
+
+section \
+  "4/4  Correct the entity before the request runs" \
+  "The generated schema gives the editor and CI the same precise feedback."
+printf '\033[2m$ delta --color-only --paging never\033[0m\n'
+diff_preview="$(printf '%s\n' \
+  'diff --git a/client.ts b/client.ts' \
+  '--- a/client.ts' \
+  '+++ b/client.ts' \
+  '@@ -3,3 +3,3 @@' \
+  ' declare const client: HomeAssistantRestClient<HaSchema>;' \
+  '-client.getState("light.demo_lmp");' \
+  '+client.getState("light.demo_lamp");' \
+  ' ' \
+  '-// The typo would become a failing API request.' \
+  '+// The typo is corrected before the request can run.')"
+printf '%s\n' "$diff_preview" \
+  | delta \
+    --color-only \
+    --paging=never \
+    --syntax-theme Dracula \
+    --minus-style 'red bold' \
+    --minus-emph-style 'red bold' \
+    --plus-style 'green bold' \
+    --plus-emph-style 'green bold' \
+    --zero-style dim
+pause_for "$diff_preview"
+printf '\n\033[1;32m✓ The generated schema catches the typo before runtime.\033[0m\n'

package/dist/codegen/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/codegen/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/codegen/cli.ts"],"names":[],"mappings":""}

package/dist/codegen/cli.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { emitSchemaModule } from "./emit.js";
+import { introspect } from "./introspect.js";
+const HELP_TEXT = `
+ha-codegen - Generate a typed Home Assistant schema from a live instance
+
+USAGE:
+  HA_TOKEN=<long-lived-access-token> ha-codegen --url <base-url> --out <path> [options]
+
+OPTIONS:
+  --url <base-url>       Home Assistant base URL (defaults to HA_URL)
+  --out <path>           Generated TypeScript module path (required)
+  --name <schema-name>   Generated schema type name (default: HaSchema)
+  --help, -h             Show this help message
+
+The generated module contains entity IDs and service definitions from your
+instance. Treat it as private: gitignore it and regenerate it when needed.
+`;
+function parseArgs(argv) {
+    const map = new Map();
+    let help = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+            continue;
+        }
+        const key = parseOptionKey(arg);
+        const next = argv[i + 1];
+        if (next?.startsWith("--") !== false) {
+            map.set(key, "true");
+            continue;
+        }
+        map.set(key, next);
+        i += 1;
+    }
+    const url = map.get("url") ?? environmentValue("HA_URL");
+    const token = environmentValue("HA_TOKEN");
+    const out = map.get("out");
+    const name = map.get("name") ?? "HaSchema";
+    if (help) {
+        return { url: "", token: "", out: "", name: "HaSchema", help: true };
+    }
+    if (url === undefined || url === "") {
+        fail("Missing --url (or HA_URL env var)");
+    }
+    if (token === undefined || token === "") {
+        fail("Missing HA_TOKEN environment variable");
+    }
+    if (out === undefined || out === "") {
+        fail("Missing --out <path>");
+    }
+    return { url, token, out, name, help: false };
+}
+function parseOptionKey(arg) {
+    if (arg?.startsWith("--") !== true) {
+        fail(`Unexpected argument: ${arg ?? ""}`);
+    }
+    const key = arg.slice(2);
+    if (key !== "url" && key !== "out" && key !== "name") {
+        fail(`Unknown option: ${arg}`);
+    }
+    return key;
+}
+function environmentValue(name) {
+    return globalThis.process.env[name];
+}
+function fail(message) {
+    console.error(`ha-codegen: ${message}`);
+    console.error("Usage: ha-codegen --url <base-url> --out <path> [--name <SchemaName>]");
+    process.exit(2);
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        process.stdout.write(HELP_TEXT);
+        return;
+    }
+    const intro = await introspect(args.url, args.token);
+    const sourceHost = safeHost(args.url);
+    const module = emitSchemaModule(intro, {
+        schemaName: args.name,
+        sourceHost,
+        generatedAt: new Date().toISOString(),
+    });
+    const outPath = path.resolve(args.out);
+    await mkdir(path.dirname(outPath), { recursive: true });
+    await writeFile(outPath, module, "utf8");
+    console.warn(`ha-codegen: wrote ${String(intro.states.length)} entities, ` +
+        `${String(totalServices(intro))} services, ` +
+        `${String(intro.events.length)} event types → ${outPath}`);
+}
+function totalServices(intro) {
+    let n = 0;
+    for (const entry of intro.services) {
+        n += Object.keys(entry.services).length;
+    }
+    return n;
+}
+function safeHost(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return "<unparsed>";
+    }
+}
+try {
+    await main();
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`ha-codegen: ${message}`);
+    process.exit(1);
+}
+//# sourceMappingURL=cli.js.map

package/dist/codegen/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/codegen/cli.ts"],"names":[],"mappings":"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"}

package/dist/codegen/emit.d.ts

@@ -0,0 +1,8 @@
+import type { HaIntrospection } from "./introspect.js";
+export type EmitOptions = {
+    schemaName: string;
+    sourceHost: string;
+    generatedAt: string;
+};
+export declare function emitSchemaModule(intro: HaIntrospection, options: EmitOptions): string;
+//# sourceMappingURL=emit.d.ts.map

package/dist/codegen/emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/codegen/emit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAQvD,MAAM,MAAM,WAAW,GAAG;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,WAAW,GACnB,MAAM,CAkBR"}

package/dist/codegen/emit.js

@@ -0,0 +1,143 @@
+import { KNOWN_EVENT_DATA } from "./known-events.js";
+import { fieldMetaFromSpec, targetDomainFromSpec, } from "./selector-to-ts.js";
+export function emitSchemaModule(intro, options) {
+    const entitiesLiteral = emitEntities(intro);
+    const servicesLiteral = emitServices(intro);
+    const eventsLiteral = emitEvents(intro);
+    const eventDataLiteral = emitEventData(intro);
+    return [
+        header(options),
+        entitiesLiteral,
+        "",
+        servicesLiteral,
+        "",
+        eventsLiteral,
+        "",
+        eventDataLiteral,
+        "",
+        emitSchemaType(options.schemaName),
+        "",
+    ].join("\n");
+}
+function header(options) {
+    return [
+        `// AUTO-GENERATED by @shepherdjerred/home-assistant ha-codegen — do not edit, do not commit.`,
+        `// Source host: ${options.sourceHost}`,
+        `// Generated at: ${options.generatedAt}`,
+        `/* eslint-disable */`,
+        ``,
+    ].join("\n");
+}
+function emitEntities(intro) {
+    const entries = [];
+    const sorted = intro.states.toSorted((a, b) => a.entity_id.localeCompare(b.entity_id));
+    for (const state of sorted) {
+        const domain = state.entity_id.includes(".")
+            ? state.entity_id.slice(0, state.entity_id.indexOf("."))
+            : "";
+        const attributes = emitAttributeSample(state.attributes);
+        entries.push(`  ${JSON.stringify(state.entity_id)}: { domain: ${JSON.stringify(domain)}, attributes: ${attributes} },`);
+    }
+    return `export const entities = {\n${entries.join("\n")}\n} as const;`;
+}
+function emitAttributeSample(attributes) {
+    const props = [];
+    const sortedKeys = Object.keys(attributes).toSorted((a, b) => a.localeCompare(b));
+    for (const key of sortedKeys) {
+        const value = attributes[key];
+        const sample = sampleValueLiteral(value);
+        if (sample !== undefined) {
+            props.push(`${JSON.stringify(key)}: ${sample}`);
+        }
+    }
+    return props.length === 0 ? `{}` : `{ ${props.join(", ")} }`;
+}
+function sampleValueLiteral(value) {
+    if (typeof value === "string") {
+        return `""`;
+    }
+    if (typeof value === "number") {
+        return `0`;
+    }
+    if (typeof value === "boolean") {
+        return `false`;
+    }
+    if (value === null) {
+        return `null`;
+    }
+    if (Array.isArray(value)) {
+        return `[] as readonly unknown[]`;
+    }
+    if (typeof value === "object") {
+        return `{}`;
+    }
+    return undefined;
+}
+function emitServices(intro) {
+    const domains = [];
+    const sorted = intro.services.toSorted((a, b) => a.domain.localeCompare(b.domain));
+    for (const entry of sorted) {
+        const services = [];
+        const serviceEntries = Object.entries(entry.services).toSorted(([a], [b]) => a.localeCompare(b));
+        for (const [serviceName, spec] of serviceEntries) {
+            const fields = Object.entries(spec.fields ?? {})
+                .toSorted(([a], [b]) => a.localeCompare(b))
+                .map(([fieldName, fieldSpec]) => {
+                const meta = fieldMetaFromSpec(fieldSpec);
+                return `      ${JSON.stringify(fieldName)}: ${emitFieldMeta(meta)}`;
+            })
+                .join(",\n");
+            const targetDomain = targetDomainFromSpec(spec.target);
+            const targetLiteral = targetDomain === undefined
+                ? ""
+                : `, target: { domain: ${JSON.stringify(targetDomain)} }`;
+            const fieldsBlock = fields === "" ? `{}` : `{\n${fields}\n    }`;
+            services.push(`    ${JSON.stringify(serviceName)}: { fields: ${fieldsBlock}${targetLiteral} },`);
+        }
+        domains.push(`  ${JSON.stringify(entry.domain)}: {\n${services.join("\n")}\n  },`);
+    }
+    return `export const services = {\n${domains.join("\n")}\n} as const;`;
+}
+function emitFieldMeta(meta) {
+    const parts = [`type: ${JSON.stringify(meta.type)}`];
+    parts.push(`required: ${meta.required ? "true" : "false"}`);
+    if (meta.domain !== undefined) {
+        parts.push(`domain: ${JSON.stringify(meta.domain)}`);
+    }
+    if (meta.options !== undefined) {
+        const opts = meta.options.map((v) => JSON.stringify(v)).join(", ");
+        parts.push(`options: [${opts}] as const`);
+    }
+    return `{ ${parts.join(", ")} }`;
+}
+function emitEvents(intro) {
+    const names = intro.events
+        .map((e) => e.event)
+        .toSorted((a, b) => a.localeCompare(b));
+    const literal = names.length === 0
+        ? "[]"
+        : `[\n${names.map((n) => `  ${JSON.stringify(n)},`).join("\n")}\n]`;
+    return `export const events = ${literal} as const;`;
+}
+function emitEventData(intro) {
+    const lines = [];
+    const names = new Set(intro.events.map((e) => e.event));
+    for (const [name, shape] of Object.entries(KNOWN_EVENT_DATA).toSorted(([a], [b]) => a.localeCompare(b))) {
+        if (!names.has(name)) {
+            continue;
+        }
+        lines.push(`  ${JSON.stringify(name)}: ${shape};`);
+    }
+    return `export type EventData = {\n${lines.join("\n")}\n};`;
+}
+function emitSchemaType(name) {
+    return [
+        `export type ${name} = {`,
+        `  entities: typeof entities;`,
+        `  services: typeof services;`,
+        `  events: (typeof events)[number];`,
+        `  eventData: EventData;`,
+        `};`,
+    ].join("\n");
+}
+//# sourceMappingURL=emit.js.map

package/dist/codegen/emit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.js","sourceRoot":"","sources":["../../src/codegen/emit.ts"],"names":[],"mappings":"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"}