@khalido/home 0.0.0-stage → 0.1.1

package/home.schema.json

@@ -0,0 +1,474 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    },
+    "location": {
+      "type": "object",
+      "properties": {
+        "latitude": {
+          "type": "number",
+          "minimum": -90,
+          "maximum": 90
+        },
+        "longitude": {
+          "type": "number",
+          "minimum": -180,
+          "maximum": 180
+        },
+        "bomForecast": {
+          "description": "BOM précis location by name or aac, e.g. Sydney",
+          "type": "string"
+        },
+        "timezone": {
+          "description": "the home's IANA time zone, where its day starts (Enphase's and Up's today, the weather's day blocks) and the zone weather times show in; the runtime's when left out",
+          "type": "string"
+        }
+      },
+      "required": [
+        "latitude",
+        "longitude"
+      ],
+      "additionalProperties": {}
+    },
+    "weather": {
+      "type": "object",
+      "properties": {
+        "sources": {
+          "description": "preference order; default open-meteo",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "bom",
+              "open-meteo",
+              "google"
+            ]
+          }
+        },
+        "pollMinutes": {
+          "type": "number",
+          "minimum": 1
+        },
+        "googleKey": {
+          "description": "env name holding a Maps Platform key, when sources has google",
+          "type": "string",
+          "pattern": "^[A-Z_][A-Z0-9_]*$"
+        }
+      },
+      "additionalProperties": {}
+    },
+    "rooms": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "starts_with",
+            "pattern": "^room-.*"
+          },
+          "name": {
+            "type": "string"
+          },
+          "floor": {
+            "type": "string"
+          },
+          "hueRoom": {
+            "description": "the Hue room, zone or grouped_light id whose lights this room's marker shows",
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "name"
+        ],
+        "additionalProperties": {}
+      }
+    },
+    "devices": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "properties": {
+              "connector": {
+                "type": "string",
+                "const": "hue"
+              },
+              "host": {
+                "type": "string",
+                "description": "the bridge's last known address"
+              },
+              "bridgeId": {
+                "type": "string",
+                "description": "the bridge id, the CN its certificate must carry: its identity"
+              },
+              "key": {
+                "type": "string",
+                "pattern": "^[A-Z_][A-Z0-9_]*$",
+                "description": "env name holding the application key from `home pair`"
+              },
+              "ca": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Signify's root CA (PEM), relative to the config file"
+              },
+              "id": {
+                "type": "string"
+              },
+              "room": {
+                "type": "string",
+                "format": "starts_with",
+                "pattern": "^room-.*"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "connector",
+              "host",
+              "bridgeId",
+              "key",
+              "ca",
+              "id"
+            ],
+            "additionalProperties": {}
+          },
+          {
+            "type": "object",
+            "properties": {
+              "connector": {
+                "type": "string",
+                "const": "daikin"
+              },
+              "host": {
+                "type": "string",
+                "description": "the unit's last known address"
+              },
+              "mac": {
+                "description": "the unit's MAC as its UDP discovery reports it: its identity",
+                "type": "string"
+              },
+              "id": {
+                "type": "string"
+              },
+              "room": {
+                "type": "string",
+                "format": "starts_with",
+                "pattern": "^room-.*"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "connector",
+              "host",
+              "id"
+            ],
+            "additionalProperties": {}
+          },
+          {
+            "type": "object",
+            "properties": {
+              "connector": {
+                "type": "string",
+                "const": "enphase"
+              },
+              "host": {
+                "type": "string",
+                "description": "the gateway's last known address"
+              },
+              "serial": {
+                "description": "the gateway's serial, as mDNS `serialnum` (and /info) report it: its identity",
+                "type": "string"
+              },
+              "token": {
+                "type": "string",
+                "minLength": 1,
+                "description": "the owner token file: JSON with a `token` field (what `home enphase login` writes), or the bare token"
+              },
+              "marker": {
+                "description": "the plan's marker where the solar array is drawn, on the roof outside any room",
+                "type": "string",
+                "format": "starts_with",
+                "pattern": "^marker-.*"
+              },
+              "capacityW": {
+                "description": "the array's rated size in watts, from the installer's paperwork; never guessed from the gateway",
+                "type": "number",
+                "exclusiveMinimum": 0
+              },
+              "id": {
+                "type": "string"
+              },
+              "room": {
+                "type": "string",
+                "format": "starts_with",
+                "pattern": "^room-.*"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "connector",
+              "host",
+              "token",
+              "id"
+            ],
+            "additionalProperties": {}
+          },
+          {
+            "type": "object",
+            "properties": {
+              "connector": {
+                "type": "string",
+                "const": "amber"
+              },
+              "key": {
+                "type": "string",
+                "pattern": "^[A-Z_][A-Z0-9_]*$",
+                "description": "env name holding the Amber API key"
+              },
+              "siteId": {
+                "description": "the site; the first active one when left out",
+                "type": "string"
+              },
+              "id": {
+                "type": "string"
+              },
+              "room": {
+                "type": "string",
+                "format": "starts_with",
+                "pattern": "^room-.*"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "connector",
+              "key",
+              "id"
+            ],
+            "additionalProperties": {}
+          },
+          {
+            "type": "object",
+            "properties": {
+              "connector": {
+                "type": "string",
+                "const": "up"
+              },
+              "key": {
+                "type": "string",
+                "pattern": "^[A-Z_][A-Z0-9_]*$",
+                "description": "env name holding the Up personal access token"
+              },
+              "account": {
+                "description": "which accounts to read, by type and ownership; every account when left out",
+                "type": "object",
+                "properties": {
+                  "accountType": {
+                    "type": "string",
+                    "enum": [
+                      "TRANSACTIONAL",
+                      "SAVER",
+                      "HOME_LOAN"
+                    ]
+                  },
+                  "ownershipType": {
+                    "type": "string",
+                    "enum": [
+                      "INDIVIDUAL",
+                      "JOINT"
+                    ]
+                  }
+                }
+              },
+              "household": {
+                "description": "what counts as the household's: Up category ids (a parent takes in its children, e.g. home) and tag labels; everything when left out",
+                "type": "object",
+                "properties": {
+                  "categories": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "tags": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                }
+              },
+              "id": {
+                "type": "string"
+              },
+              "room": {
+                "type": "string",
+                "format": "starts_with",
+                "pattern": "^room-.*"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "connector",
+              "key",
+              "id"
+            ],
+            "additionalProperties": {}
+          },
+          {
+            "type": "object",
+            "properties": {
+              "connector": {
+                "type": "string",
+                "const": "cast"
+              },
+              "name": {
+                "type": "string",
+                "description": "the device's or group's name in the Google Home app (mDNS fn), for display; `home discover --write` fills it and refreshes it after a rename"
+              },
+              "castId": {
+                "type": "string",
+                "description": "the mDNS id, the stable identity; `home discover --write` fills it"
+              },
+              "id": {
+                "type": "string"
+              },
+              "room": {
+                "type": "string",
+                "format": "starts_with",
+                "pattern": "^room-.*"
+              }
+            },
+            "required": [
+              "connector",
+              "name",
+              "castId",
+              "id"
+            ],
+            "additionalProperties": {}
+          },
+          {
+            "type": "object",
+            "properties": {
+              "connector": {
+                "type": "string",
+                "const": "printers"
+              },
+              "name": {
+                "type": "string",
+                "description": "the printer's name for display (mDNS `ty`, or its instance name); `home discover --write` fills it"
+              },
+              "uuid": {
+                "type": "string",
+                "description": "the printer's UUID from its mDNS TXT record, the stable identity; `home discover --write` fills it"
+              },
+              "host": {
+                "description": "the address it last answered at; discovery refreshes it",
+                "type": "string"
+              },
+              "port": {
+                "description": "its IPP port (631 plain, 443 TLS); discovery fills it",
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              },
+              "offlineDays": {
+                "description": "days an unreachable printer shows as offline with its last-seen time before its entry flags it as long gone; default 14",
+                "type": "number",
+                "exclusiveMinimum": 0
+              },
+              "id": {
+                "type": "string"
+              },
+              "room": {
+                "type": "string",
+                "format": "starts_with",
+                "pattern": "^room-.*"
+              }
+            },
+            "required": [
+              "connector",
+              "name",
+              "uuid",
+              "id"
+            ],
+            "additionalProperties": {}
+          },
+          {
+            "type": "object",
+            "properties": {
+              "connector": {
+                "type": "string",
+                "const": "spotify"
+              },
+              "url": {
+                "description": "Soloist's WebSocket, as its --ws flag opens it; ws://127.0.0.1:9091 when left out. It has no auth: keep it on loopback",
+                "type": "string",
+                "format": "uri"
+              },
+              "maxVolume": {
+                "description": "the loudest a write may set (0–100), and where a first play that starts above it is lowered to (Soloist issue #23)",
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 100
+              },
+              "repairStalls": {
+                "description": "when playback stalls while Soloist says playing (Soloist issue #5), try once per track to restart it: a seek, then pause and play, or a skip when it is stuck past the track's end. Off unless set",
+                "type": "boolean"
+              },
+              "id": {
+                "type": "string"
+              },
+              "room": {
+                "type": "string",
+                "format": "starts_with",
+                "pattern": "^room-.*"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "connector",
+              "id"
+            ],
+            "additionalProperties": {}
+          }
+        ]
+      }
+    },
+    "plan": {
+      "description": "the drawing, by path relative to this file",
+      "type": "object",
+      "properties": {
+        "svg": {
+          "type": "string",
+          "minLength": 1
+        },
+        "json": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": {}
+    }
+  },
+  "additionalProperties": {}
+}

package/llms.txt

@@ -0,0 +1,32 @@
+# home.ts
+
+> Small, typed home automation for TypeScript, published on npm as `@khalido/home`, with a `home` command. It starts with one home's devices: Philips Hue, a Daikin AC, Enphase solar, Google Cast, AirPrint printers and a Spotify Soloist speaker on the local network; Amber Electric prices, Up Bank spending and the weather from the cloud. Runs on Bun 1.4+ and Node 24+; the CLI needs Bun. MIT.
+
+The library never reads the environment or a file: callers pass addresses, keys and a `fetch`. `createHome` runs integrations and keeps one typed snapshot; `loadHome` builds them from a home config that names env vars, never secrets. Every field a device reports is optional, and odd readings pass through in `anomaly` rather than being corrected. Writes go through a per-device lane: spaced, bursts merged.
+
+## Start here
+
+- [README](https://raw.githubusercontent.com/khalido/home.ts/main/README.md): what it is, install, the connectors
+- [Using it from an app](https://raw.githubusercontent.com/khalido/home.ts/main/docs/using.md): createHome, loadHome, health, change events, writes, energy
+- [The home config](https://raw.githubusercontent.com/khalido/home.ts/main/docs/config.md): devices by identity, rooms, discovery
+- [The home command](https://raw.githubusercontent.com/khalido/home.ts/main/docs/cli.md): status, probe, discover, per-connector verbs
+- [Agent skill: use-home](https://raw.githubusercontent.com/khalido/home.ts/main/skills/use-home/SKILL.md): reading safely, connecting, the rules for writes
+
+## Connectors
+
+- [hue](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/hue/README.md): lights, rooms, scenes over the bridge's event stream
+- [daikin](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/daikin/README.md): the AC over its local API
+- [enphase](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/enphase/README.md): solar from the IQ Gateway
+- [cast](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/cast/README.md): Cast devices and groups, volume, announcements
+- [printers](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/printers/README.md): AirPrint printers over IPP
+- [spotify](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/spotify/README.md): a Spotify Soloist speaker: state, confirmed writes, duck and interrupt, change events, stall watch
+- [amber](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/amber/README.md): live electricity prices and forecast
+- [up](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/up/README.md): household spending by category
+- [weather](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/weather/README.md): BOM, Open-Meteo and Google; hourly, day blocks, rain soon
+
+## Optional
+
+- [Why it is shaped this way](https://raw.githubusercontent.com/khalido/home.ts/main/docs/philosophy.md)
+- [Decisions](https://raw.githubusercontent.com/khalido/home.ts/main/docs/decisions.md): what was decided and why, newest last
+- [Adding a connector](https://raw.githubusercontent.com/khalido/home.ts/main/AGENTS.md)
+- [Changelog](https://raw.githubusercontent.com/khalido/home.ts/main/CHANGELOG.md)

package/package.json

@@ -1,6 +1,145 @@
 {
   "name": "@khalido/home",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "home.ts: small, typed home automation for TypeScript: Hue, Daikin, Enphase, Google Cast, AirPrint printers and a Spotify Soloist speaker on the local network; Amber prices, Up Bank spending and the weather from the cloud.",
+  "license": "MIT",
+  "author": "Khalid Omar",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/khalido/home.ts.git"
+  },
+  "homepage": "https://github.com/khalido/home.ts#readme",
+  "bugs": "https://github.com/khalido/home.ts/issues",
+  "keywords": [
+    "philips-hue",
+    "hue",
+    "enphase",
+    "envoy",
+    "daikin",
+    "home-automation",
+    "bun",
+    "amber-electric",
+    "weather",
+    "chromecast",
+    "google-cast",
+    "bom",
+    "airprint",
+    "ipp",
+    "printer",
+    "spotify",
+    "spotify-connect",
+    "up-bank"
+  ],
+  "engines": {
+    "bun": ">=1.4",
+    "node": ">=24"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./hue": {
+      "types": "./dist/connectors/hue/index.d.ts",
+      "import": "./dist/connectors/hue/index.js"
+    },
+    "./daikin": {
+      "types": "./dist/connectors/daikin/index.d.ts",
+      "import": "./dist/connectors/daikin/index.js"
+    },
+    "./enphase": {
+      "types": "./dist/connectors/enphase/index.d.ts",
+      "import": "./dist/connectors/enphase/index.js"
+    },
+    "./amber": {
+      "types": "./dist/connectors/amber/index.d.ts",
+      "import": "./dist/connectors/amber/index.js"
+    },
+    "./up": {
+      "types": "./dist/connectors/up/index.d.ts",
+      "import": "./dist/connectors/up/index.js"
+    },
+    "./weather": {
+      "types": "./dist/connectors/weather/index.d.ts",
+      "import": "./dist/connectors/weather/index.js"
+    },
+    "./weather/ftp": {
+      "types": "./dist/connectors/weather/ftp.d.ts",
+      "import": "./dist/connectors/weather/ftp.js"
+    },
+    "./cast": {
+      "types": "./dist/connectors/cast/index.d.ts",
+      "import": "./dist/connectors/cast/index.js"
+    },
+    "./printers": {
+      "types": "./dist/connectors/printers/index.d.ts",
+      "import": "./dist/connectors/printers/index.js"
+    },
+    "./spotify": {
+      "types": "./dist/connectors/spotify/index.d.ts",
+      "import": "./dist/connectors/spotify/index.js"
+    },
+    "./cast/tls": {
+      "types": "./dist/connectors/cast/tls.d.ts",
+      "import": "./dist/connectors/cast/tls.js"
+    },
+    "./cast/serve": {
+      "types": "./dist/connectors/cast/serve.d.ts",
+      "import": "./dist/connectors/cast/serve.js"
+    },
+    "./node": {
+      "types": "./dist/node-fetch.d.ts",
+      "import": "./dist/node-fetch.js"
+    },
+    "./finders": {
+      "types": "./dist/finders-entry.d.ts",
+      "import": "./dist/finders-entry.js"
+    }
+  },
+  "bin": {
+    "home": "src/cli/main.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "llms.txt",
+    ".env.example",
+    "dist",
+    "docs",
+    "!docs/handover.md",
+    "!docs/publishing.md",
+    "examples",
+    "skills",
+    "src",
+    "home.schema.json"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test",
+    "check": "bun fmt --check && bun check --no-script && bun check --no-script -p tsconfig.build.json && bun check --no-script -p tsconfig.node.json",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsc -p tsconfig.node.json",
+    "bench": "bun bench/bench.ts",
+    "prepublishOnly": "bun run check && bun test && bun run build",
+    "schema": "bun scripts/schema.ts",
+    "gen": "bun scripts/gen.ts"
+  },
+  "dependencies": {
+    "basic-ftp": "^6.2.3",
+    "cac": "^7.1.0",
+    "fast-xml-parser": "^5.11.2",
+    "jsonc-parser": "^3.3.1",
+    "suncalc": "^2.1.1",
+    "undici": "^8.12.3",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.4",
+    "mitata": "^1.0.34",
+    "typescript": "^7.0.2"
+  }
+}