@hashsome/integration.home-assistant 0.0.0-stage → 0.2.0

package/dist/mappers/light.js

@@ -0,0 +1,49 @@
+import { baseOf, num, strings } from './common.js';
+const COLOR_MODES = ['hs', 'xy', 'rgb', 'rgbw', 'rgbww'];
+function colorOf(a) {
+    const kelvin = num(a.color_temp_kelvin);
+    if (a.color_mode === 'color_temp' && kelvin !== undefined) {
+        return { mode: 'temperature', kelvin };
+    }
+    const hs = a.hs_color;
+    if (Array.isArray(hs) && typeof hs[0] === 'number' && typeof hs[1] === 'number') {
+        const rgb = a.rgb_color;
+        return {
+            mode: 'color',
+            hue: hs[0],
+            saturation: hs[1],
+            ...(Array.isArray(rgb) && rgb.length >= 3 && rgb.every((n) => typeof n === 'number')
+                ? { rgb: [rgb[0], rgb[1], rgb[2]] }
+                : {}),
+        };
+    }
+    return kelvin !== undefined ? { mode: 'temperature', kelvin } : undefined;
+}
+export function mapLight(entity) {
+    const a = entity.attributes;
+    const modes = strings(a.supported_color_modes);
+    const brightness = num(a.brightness);
+    const dimmable = modes.some((mode) => mode !== 'onoff' && mode !== 'unknown');
+    const colorTemperature = modes.includes('color_temp');
+    const color = colorOf(a);
+    return {
+        kind: 'light',
+        ...baseOf(entity),
+        on: entity.state === 'on',
+        ...(brightness !== undefined ? { brightness: brightness / 255 } : {}),
+        ...(color ? { color } : {}),
+        capabilities: {
+            brightness: dimmable,
+            colorTemperature,
+            color: modes.some((mode) => COLOR_MODES.includes(mode)),
+            ...(colorTemperature
+                ? {
+                    kelvinRange: {
+                        min: num(a.min_color_temp_kelvin) ?? 2000,
+                        max: num(a.max_color_temp_kelvin) ?? 6500,
+                    },
+                }
+                : {}),
+        },
+    };
+}

package/dist/mappers/media-player.d.ts

@@ -0,0 +1,3 @@
+import type { EntityInput } from '@hashsome/core';
+import type { HassEntity } from 'home-assistant-js-websocket';
+export declare function mapMediaPlayer(entity: HassEntity, toAssetUrl?: (path: string) => string): EntityInput;

package/dist/mappers/media-player.js

@@ -0,0 +1,69 @@
+import { baseOf, fileUrl, num, str } from './common.js';
+/** `MediaPlayerEntityFeature` bit flags from Home Assistant. */
+const FEATURE = {
+    seek: 2,
+    volumeSet: 4,
+    volumeMute: 8,
+    previous: 16,
+    next: 32,
+    shuffle: 32768,
+    browse: 131072,
+};
+const PLAYBACK = {
+    playing: 'playing',
+    paused: 'paused',
+    idle: 'idle',
+    standby: 'idle',
+    on: 'idle',
+    off: 'off',
+    buffering: 'buffering',
+};
+export function mapMediaPlayer(entity, toAssetUrl = (path) => path) {
+    const a = entity.attributes;
+    const features = num(a.supported_features);
+    const has = (flag, fallback) => features === undefined ? fallback : (features & flag) !== 0;
+    const volume = num(a.volume_level);
+    const title = str(a.media_title);
+    const artist = str(a.media_artist);
+    const album = str(a.media_album_name);
+    const picture = str(a.entity_picture_local) ?? str(a.entity_picture);
+    const artworkUrl = picture ? fileUrl(picture, toAssetUrl) : undefined;
+    const position = num(a.media_position);
+    const duration = num(a.media_duration);
+    const positionUpdatedAt = str(a.media_position_updated_at);
+    const shuffle = typeof a.shuffle === 'boolean' ? a.shuffle : undefined;
+    return {
+        kind: 'mediaPlayer',
+        ...baseOf(entity),
+        playback: PLAYBACK[entity.state] ?? 'idle',
+        muted: a.is_volume_muted === true,
+        ...(volume !== undefined ? { volume } : {}),
+        ...(title || artist || album || artworkUrl
+            ? {
+                media: {
+                    ...(title ? { title } : {}),
+                    ...(artist ? { artist } : {}),
+                    ...(album ? { album } : {}),
+                    ...(artworkUrl ? { artworkUrl } : {}),
+                },
+            }
+            : {}),
+        ...(shuffle !== undefined ? { shuffle } : {}),
+        ...(position !== undefined ? { position } : {}),
+        ...(duration !== undefined ? { duration } : {}),
+        ...(position !== undefined && positionUpdatedAt ? { positionUpdatedAt } : {}),
+        capabilities: {
+            volume: volume !== undefined || has(FEATURE.volumeSet, false),
+            mute: a.is_volume_muted !== undefined || has(FEATURE.volumeMute, false),
+            next: has(FEATURE.next, true),
+            previous: has(FEATURE.previous, true),
+            browse: has(FEATURE.browse, false),
+            // Home Assistant's browse contract has no search.
+            search: false,
+            seek: has(FEATURE.seek, false),
+            shuffle: has(FEATURE.shuffle, false),
+            transfer: false,
+            group: false,
+        },
+    };
+}

package/dist/mappers/simple.d.ts

@@ -0,0 +1,8 @@
+import type { EntityInput } from '@hashsome/core';
+import type { HassEntity } from 'home-assistant-js-websocket';
+export declare function mapSensor(entity: HassEntity): EntityInput;
+/** `on` for an on/off thing; for a lock, `locked`. */
+export declare function mapSwitch(entity: HassEntity): EntityInput;
+export declare function mapAction(entity: HassEntity): EntityInput;
+export declare function mapPerson(entity: HassEntity, toAssetUrl?: (path: string) => string): EntityInput;
+export declare function mapGeneric(entity: HassEntity): EntityInput;

package/dist/mappers/simple.js

@@ -0,0 +1,38 @@
+import { baseOf, fileUrl, num, str } from './common.js';
+export function mapSensor(entity) {
+    const unit = str(entity.attributes.unit_of_measurement);
+    const measurement = str(entity.attributes.device_class);
+    const numeric = entity.state.trim() === '' ? undefined : num(Number(entity.state));
+    return {
+        kind: 'sensor',
+        ...baseOf(entity),
+        value: entity.state,
+        ...(numeric !== undefined ? { numeric } : {}),
+        ...(unit ? { unit } : {}),
+        ...(measurement ? { measurement } : {}),
+    };
+}
+/** `on` for an on/off thing; for a lock, `locked`. */
+export function mapSwitch(entity) {
+    const on = entity.state === 'on' || entity.state === 'locked';
+    return { kind: 'switch', ...baseOf(entity), on };
+}
+export function mapAction(entity) {
+    const last = str(entity.attributes.last_triggered);
+    return { kind: 'action', ...baseOf(entity), ...(last ? { lastTriggered: last } : {}) };
+}
+export function mapPerson(entity, toAssetUrl = (path) => path) {
+    const raw = str(entity.attributes.entity_picture);
+    const picture = raw ? fileUrl(raw, toAssetUrl) : undefined;
+    return {
+        kind: 'person',
+        ...baseOf(entity),
+        location: entity.state,
+        home: entity.state === 'home',
+        ...(picture ? { pictureUrl: picture } : {}),
+    };
+}
+export function mapGeneric(entity) {
+    const unit = str(entity.attributes.unit_of_measurement);
+    return { kind: 'generic', ...baseOf(entity), value: entity.state, ...(unit ? { unit } : {}) };
+}

package/dist/mappers/weather.d.ts

@@ -0,0 +1,5 @@
+import { type EntityInput } from '@hashsome/core';
+import type { HassEntity } from 'home-assistant-js-websocket';
+/** A `weather.*` entity: its state is the current condition, its attributes the current readings
+ * (the forecast is separate, not part of the entity's state: see `forecast()`). */
+export declare function mapWeather(entity: HassEntity): EntityInput;

package/dist/mappers/weather.js

@@ -0,0 +1,40 @@
+import { WEATHER_CONDITIONS } from '@hashsome/core';
+import { forecastsOf } from '../forecast.js';
+import { baseOf, bearing, num, str } from './common.js';
+const isCondition = (state) => WEATHER_CONDITIONS.includes(state);
+/** A `weather.*` entity: its state is the current condition, its attributes the current readings
+ * (the forecast is separate, not part of the entity's state: see `forecast()`). */
+export function mapWeather(entity) {
+    const a = entity.attributes;
+    const temperature = num(a.temperature);
+    const unit = str(a.temperature_unit);
+    const humidity = num(a.humidity);
+    const windSpeed = num(a.wind_speed);
+    const windBearing = bearing(a.wind_bearing);
+    const windUnit = str(a.wind_speed_unit);
+    const uvIndex = num(a.uv_index);
+    const cloudCoverage = num(a.cloud_coverage);
+    const apparentTemperature = num(a.apparent_temperature);
+    const pressure = num(a.pressure);
+    const pressureUnit = str(a.pressure_unit);
+    const precipitationUnit = str(a.precipitation_unit);
+    const forecasts = forecastsOf(num(a.supported_features));
+    return {
+        kind: 'weather',
+        ...baseOf(entity),
+        condition: isCondition(entity.state) ? entity.state : 'unknown',
+        ...(temperature !== undefined ? { temperature } : {}),
+        ...(unit ? { unit } : {}),
+        ...(humidity !== undefined ? { humidity } : {}),
+        ...(windSpeed !== undefined ? { windSpeed } : {}),
+        ...(windBearing !== undefined ? { windBearing } : {}),
+        ...(windUnit ? { windUnit } : {}),
+        ...(uvIndex !== undefined ? { uvIndex } : {}),
+        ...(cloudCoverage !== undefined ? { cloudCoverage } : {}),
+        ...(apparentTemperature !== undefined ? { apparentTemperature } : {}),
+        ...(pressure !== undefined ? { pressure } : {}),
+        ...(pressureUnit ? { pressureUnit } : {}),
+        ...(precipitationUnit ? { precipitationUnit } : {}),
+        ...(forecasts.length > 0 ? { forecasts } : {}),
+    };
+}

package/dist/mock.d.ts

@@ -0,0 +1,11 @@
+import { MockIntegration, type EntityInput } from '@hashsome/core';
+export interface HomeAssistantMockOptions {
+    /** Integration id. Defaults to `ha`. */
+    id?: string;
+    /** Extra entities, by local id; they replace a default with the same id. */
+    entities?: Record<string, EntityInput>;
+}
+/** A Home Assistant integration that needs no Home Assistant: representative devices, mapped the
+ * same way real ones are, and commands that change their state. For tests, the gallery and
+ * dashboards under development. */
+export declare function createMock(options?: HomeAssistantMockOptions): MockIntegration;

package/dist/mock.js

@@ -0,0 +1,114 @@
+import { MockIntegration, mockLibrary } from '@hashsome/core';
+import { mapEntity } from './mappers/index.js';
+const state = (id, value, attributes = {}) => ({
+    entity_id: id,
+    state: value,
+    attributes,
+    last_changed: '2026-01-01T00:00:00.000Z',
+    last_updated: '2026-01-01T00:00:00.000Z',
+    context: { id: 'mock', parent_id: null, user_id: null },
+});
+/** What Home Assistant reports for a representative home: every domain the mappers understand,
+ * and the states a dashboard has to handle (off, unavailable, unknown). Raw states, so the mock
+ * is built by the same mapping the real integration uses. */
+const states = () => [
+    state('light.plain', 'on', { friendly_name: 'Lamp', supported_color_modes: ['onoff'] }),
+    state('light.dimmable', 'on', {
+        friendly_name: 'Dimmable light',
+        supported_color_modes: ['brightness'],
+        brightness: 153,
+    }),
+    state('light.tunable', 'on', {
+        friendly_name: 'Tunable white',
+        supported_color_modes: ['color_temp'],
+        color_mode: 'color_temp',
+        brightness: 255,
+        color_temp_kelvin: 2700,
+        min_color_temp_kelvin: 2000,
+        max_color_temp_kelvin: 6500,
+    }),
+    state('light.color', 'off', {
+        friendly_name: 'Color light',
+        supported_color_modes: ['hs'],
+        brightness: 255,
+        hs_color: [280, 80],
+    }),
+    state('light.unavailable', 'unavailable', { friendly_name: 'Unplugged light' }),
+    state('climate.heater', 'heat', {
+        friendly_name: 'Heater',
+        hvac_modes: ['off', 'heat'],
+        temperature: 21,
+        current_temperature: 19.4,
+        min_temp: 5,
+        max_temp: 30,
+        target_temp_step: 0.5,
+    }),
+    state('climate.thermostat', 'off', {
+        friendly_name: 'Thermostat',
+        hvac_modes: ['off', 'heat', 'cool', 'auto'],
+        temperature: 21.5,
+        current_temperature: 18.8,
+        preset_modes: ['home', 'away'],
+        preset_mode: 'home',
+    }),
+    state('sensor.temperature', '18.4', {
+        friendly_name: 'Temperature',
+        device_class: 'temperature',
+        unit_of_measurement: '°C',
+    }),
+    state('sensor.humidity', '52', {
+        friendly_name: 'Humidity',
+        device_class: 'humidity',
+        unit_of_measurement: '%',
+    }),
+    state('sensor.power', '9', {
+        friendly_name: 'Power',
+        device_class: 'power',
+        unit_of_measurement: 'W',
+    }),
+    state('sensor.energy', '84.3', {
+        friendly_name: 'Energy',
+        device_class: 'energy',
+        unit_of_measurement: 'kWh',
+    }),
+    state('sensor.not_reporting', 'unknown', {
+        friendly_name: 'Silent sensor',
+        device_class: 'temperature',
+    }),
+    state('binary_sensor.door', 'off', { friendly_name: 'Door', device_class: 'door' }),
+    state('person.dan', 'home', { friendly_name: 'Dan' }),
+    state('person.alex', 'not_home', { friendly_name: 'Alex' }),
+    state('scene.movie_night', 'scening', { friendly_name: 'Movie night' }),
+    state('script.shower', 'off', { friendly_name: 'Shower' }),
+    state('vacuum.robot', 'docked', { friendly_name: 'Robot vacuum' }),
+    state('switch.coffee_maker', 'off', { friendly_name: 'Coffee maker' }),
+    state('fan.exhaust', 'off', { friendly_name: 'Exhaust fan' }),
+    state('lock.front_door', 'locked', { friendly_name: 'Front door' }),
+    state('media_player.living_room', 'playing', {
+        friendly_name: 'Living room',
+        media_title: 'Blank Space',
+        media_artist: 'More More',
+        volume_level: 0.4,
+        media_position: 64,
+        media_duration: 231,
+        media_position_updated_at: new Date().toISOString(),
+        shuffle: false,
+        // play, pause, seek, volume, mute, previous, next, shuffle and browse.
+        supported_features: 163967,
+    }),
+    state('input_boolean.guest_mode', 'off', { friendly_name: 'Guest mode' }),
+];
+/** A Home Assistant integration that needs no Home Assistant: representative devices, mapped the
+ * same way real ones are, and commands that change their state. For tests, the gallery and
+ * dashboards under development. */
+export function createMock(options = {}) {
+    const entities = {};
+    for (const hass of states()) {
+        entities[hass.entity_id] = mapEntity(hass, { temperatureUnit: '°C' });
+    }
+    return new MockIntegration({
+        id: options.id ?? 'ha',
+        library: mockLibrary(),
+        entities: { ...entities, ...options.entities },
+    });
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@hashsome/integration.home-assistant",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Home Assistant integration: entities, services, area/entity registry",
+  "type": "module",
+  "dependencies": {
+    "@hashsome/core": "0.2.0",
+    "home-assistant-js-websocket": "9.7.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./mock": {
+      "types": "./dist/mock.d.ts",
+      "default": "./dist/mock.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "license": "GPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dstoyanoff/hashsome.git",
+    "directory": "packages/integrations/home-assistant"
+  },
+  "homepage": "https://github.com/dstoyanoff/hashsome#readme",
+  "bugs": "https://github.com/dstoyanoff/hashsome/issues",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "states": "node scripts/print-states.ts",
+    "build": "tsc -b tsconfig.build.json"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.