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

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { type HassEntities } from 'home-assistant-js-websocket';
+import { BaseIntegration, type BrowseQuery, type BrowseResult, type ForecastQuery, type ForecastResult, type HistoryQuery, type HistoryResult, type LogbookQuery, type LogbookResult, type Unsubscribe } from '@hashsome/core';
+export interface HaArea {
+    area_id: string;
+    name: string;
+    icon?: string | null;
+}
+export interface HaEntityRegistryEntry {
+    entity_id: string;
+    name?: string | null;
+    original_name?: string | null;
+    area_id?: string | null;
+    device_id?: string | null;
+    icon?: string | null;
+    disabled_by?: string | null;
+    hidden_by?: string | null;
+}
+/** Thin seam over `home-assistant-js-websocket` so the integration can be tested without a server. */
+export interface HaClient {
+    subscribeEntities(listener: (entities: HassEntities) => void): Unsubscribe;
+    callService(domain: string, service: string, data?: Record<string, unknown>, target?: {
+        entity_id?: string[];
+    }): Promise<unknown>;
+    sendCommand<T>(message: {
+        type: string;
+    } & Record<string, unknown>): Promise<T>;
+    on(event: 'ready' | 'disconnected' | 'reconnect-error', listener: () => void): void;
+    close(): void;
+}
+export interface HomeAssistantOptions {
+    /** Base URL, e.g. `http://homeassistant.local:8123`. */
+    url: string;
+    /** Long-lived access token. */
+    token: string;
+    /** Integration id used in entity refs. Defaults to `ha`. */
+    id?: string;
+    /** Home Assistant reports its temperature unit in its own config, not per entity. Default `°C`. */
+    temperatureUnit?: '°C' | '°F';
+    /** Override for tests. */
+    createClient?: () => Promise<HaClient>;
+}
+export declare function createHaClient(options: {
+    url: string;
+    token: string;
+}): Promise<HaClient>;
+export declare class HomeAssistantIntegration extends BaseIntegration {
+    #private;
+    readonly id: string;
+    constructor(options: HomeAssistantOptions);
+    connect(): Promise<void>;
+    disconnect(): void;
+    command(entityId: string, name: string, args?: Record<string, unknown>): Promise<void>;
+    /**
+     * A sensor's past values from Home Assistant's long-term statistics: the average per bucket for a
+     * measurement (temperature, power), or how much the counter grew per bucket for a running total
+     * (energy). An entity that has no statistics (not a sensor with a `state_class`) has no points.
+     */
+    history(entityId: string, query: HistoryQuery): Promise<HistoryResult>;
+    /**
+     * A weather entity's forecast, from the `weather.get_forecasts` service (the forecast is no longer
+     * part of the entity's state). An entity that does not give that kind of forecast has no points.
+     */
+    forecast(entityId: string, query: ForecastQuery): Promise<ForecastResult>;
+    /**
+     * What happened to an entity in the last week and who or what caused it, from the logbook
+     * (`logbook/get_events`), newest first. A change by a person is named from the `person` entities
+     * (each carries its Home Assistant user id), so no admin rights are needed to resolve it.
+     */
+    logbook(entityId: string, query: LogbookQuery): Promise<LogbookResult>;
+    /** A file Home Assistant serves (artwork, a person's picture), fetched with the token. Only a
+     * path on Home Assistant itself is accepted, never another address. */
+    fetchAsset(path: string): Promise<Response>;
+    /** One level of the player's own media library, from `media_player/browse_media`. */
+    browse(entityId: string, query: BrowseQuery): Promise<BrowseResult>;
+    /** Calls any Home Assistant service: `{ domain, service, entityIds?, data? }`. */
+    callRaw(request: Record<string, unknown>): Promise<unknown>;
+    getAreas(): Promise<HaArea[]>;
+    getEntityRegistry(): Promise<HaEntityRegistryEntry[]>;
+}

package/dist/index.js

@@ -0,0 +1,246 @@
+import { callService as haCallService, createConnection, createLongLivedTokenAuth, subscribeEntities, } from 'home-assistant-js-websocket';
+import { assetUrl, BaseIntegration, UnknownEntityError, } from '@hashsome/core';
+import { decodeItemId, toBrowseItem } from './browse.js';
+import { DEFAULT_BUCKET, PERIODS, RANGE_MS, } from './history.js';
+import { toServiceRequest } from './commands.js';
+import { toForecastPoints } from './forecast.js';
+import { toLogbookEntries } from './logbook.js';
+import { mapEntity } from './mappers/index.js';
+export async function createHaClient(options) {
+    const auth = createLongLivedTokenAuth(options.url, options.token);
+    const connection = await createConnection({ auth });
+    return {
+        subscribeEntities: (listener) => subscribeEntities(connection, listener),
+        callService: (domain, service, data, target) => haCallService(connection, domain, service, data, target),
+        sendCommand: (message) => connection.sendMessagePromise(message),
+        on: (event, listener) => connection.addEventListener(event, listener),
+        close: () => connection.close(),
+    };
+}
+/** How far back the logbook is read: enough for the latest handful of entries of most devices. */
+const LOGBOOK_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+export class HomeAssistantIntegration extends BaseIntegration {
+    id;
+    #options;
+    #client;
+    #stopEntities;
+    #cache = new Map();
+    constructor(options) {
+        super();
+        this.id = options.id ?? 'ha';
+        this.#options = options;
+    }
+    async connect() {
+        if (this.#client) {
+            return;
+        }
+        this.setStatus('connecting');
+        try {
+            const client = await (this.#options.createClient ?? (() => createHaClient(this.#options)))();
+            this.#client = client;
+            client.on('ready', () => this.setStatus('connected'));
+            client.on('disconnected', () => this.setStatus('disconnected'));
+            client.on('reconnect-error', () => this.setStatus('error'));
+            // `connect()` resolves only once the first full set of entities has arrived, so
+            // `listEntities()` is complete — and "unknown entity" can be decided — from then on.
+            const firstLoad = new Promise((resolve) => {
+                this.#stopEntities = client.subscribeEntities((entities) => {
+                    this.#applyEntities(entities);
+                    resolve();
+                });
+            });
+            await firstLoad;
+            this.setStatus('connected');
+        }
+        catch (error) {
+            this.setStatus('error');
+            throw error;
+        }
+    }
+    disconnect() {
+        this.#stopEntities?.();
+        this.#stopEntities = undefined;
+        this.#client?.close();
+        this.#client = undefined;
+        this.setStatus('disconnected');
+    }
+    async command(entityId, name, args) {
+        const client = this.#requireClient();
+        const entity = this.getEntity(entityId);
+        if (!entity) {
+            throw new UnknownEntityError(this.id, entityId);
+        }
+        const { domain, service, data } = toServiceRequest(entityId, entity, name, args);
+        await client.callService(domain, service, data, { entity_id: [entityId] });
+    }
+    #assetUrl = (path) => assetUrl(this.id, path);
+    /**
+     * A sensor's past values from Home Assistant's long-term statistics: the average per bucket for a
+     * measurement (temperature, power), or how much the counter grew per bucket for a running total
+     * (energy). An entity that has no statistics (not a sensor with a `state_class`) has no points.
+     */
+    async history(entityId, query) {
+        const client = this.#requireClient();
+        if (!this.getEntity(entityId)) {
+            throw new UnknownEntityError(this.id, entityId);
+        }
+        const [meta] = await client.sendCommand({
+            type: 'recorder/get_statistics_metadata',
+            statistic_ids: [entityId],
+        });
+        if (!meta || (!meta.has_sum && !meta.has_mean)) {
+            return { points: [], kind: 'measurement' };
+        }
+        const total = meta.has_sum;
+        const field = total ? 'change' : 'mean';
+        const bucket = query.bucket ?? DEFAULT_BUCKET[query.range];
+        const found = await client.sendCommand({
+            type: 'recorder/statistics_during_period',
+            start_time: new Date(Date.now() - RANGE_MS[query.range]).toISOString(),
+            statistic_ids: [entityId],
+            period: PERIODS[bucket],
+            types: [field],
+        });
+        const points = (found[entityId] ?? []).flatMap((row) => {
+            const value = row[field];
+            return typeof value === 'number'
+                ? [{ timestamp: new Date(row.start).toISOString(), value }]
+                : [];
+        });
+        const unit = meta.statistics_unit_of_measurement;
+        return { points, kind: total ? 'total' : 'measurement', ...(unit ? { unit } : {}) };
+    }
+    /**
+     * A weather entity's forecast, from the `weather.get_forecasts` service (the forecast is no longer
+     * part of the entity's state). An entity that does not give that kind of forecast has no points.
+     */
+    async forecast(entityId, query) {
+        const client = this.#requireClient();
+        const entity = this.getEntity(entityId);
+        if (entity?.kind !== 'weather') {
+            throw new UnknownEntityError(this.id, entityId);
+        }
+        if (!entity.forecasts?.includes(query.type)) {
+            return { type: query.type, points: [] };
+        }
+        const answer = await client.sendCommand({
+            type: 'call_service',
+            domain: 'weather',
+            service: 'get_forecasts',
+            service_data: { type: query.type },
+            target: { entity_id: entityId },
+            return_response: true,
+        });
+        return {
+            type: query.type,
+            points: toForecastPoints(answer.response?.[entityId]?.forecast),
+            ...(entity.unit ? { unit: entity.unit } : {}),
+            ...(entity.windUnit ? { windUnit: entity.windUnit } : {}),
+            ...(entity.precipitationUnit ? { precipitationUnit: entity.precipitationUnit } : {}),
+            ...(entity.pressureUnit ? { pressureUnit: entity.pressureUnit } : {}),
+        };
+    }
+    /**
+     * What happened to an entity in the last week and who or what caused it, from the logbook
+     * (`logbook/get_events`), newest first. A change by a person is named from the `person` entities
+     * (each carries its Home Assistant user id), so no admin rights are needed to resolve it.
+     */
+    async logbook(entityId, query) {
+        const client = this.#requireClient();
+        if (!this.getEntity(entityId)) {
+            throw new UnknownEntityError(this.id, entityId);
+        }
+        const end = Date.now();
+        const events = await client.sendCommand({
+            type: 'logbook/get_events',
+            start_time: new Date(end - LOGBOOK_WINDOW_MS).toISOString(),
+            end_time: new Date(end).toISOString(),
+            entity_ids: [entityId],
+        });
+        const personByUserId = new Map();
+        for (const entity of this.listEntities()) {
+            const userId = entity.kind === 'person' ? entity.raw?.attributes : undefined;
+            const id = userId?.user_id;
+            if (typeof id === 'string') {
+                personByUserId.set(id, entity.name);
+            }
+        }
+        return {
+            entries: toLogbookEntries(events, { personByUserId, nameOf: (id) => this.getEntity(id)?.name }, query.limit ?? 20),
+        };
+    }
+    /** A file Home Assistant serves (artwork, a person's picture), fetched with the token. Only a
+     * path on Home Assistant itself is accepted, never another address. */
+    async fetchAsset(path) {
+        const base = new URL(this.#options.url);
+        const target = new URL(path, base);
+        if (!path.startsWith('/') || path.startsWith('//') || target.origin !== base.origin) {
+            throw new Error('Not a path on Home Assistant');
+        }
+        return fetch(target, { headers: { Authorization: `Bearer ${this.#options.token}` } });
+    }
+    /** One level of the player's own media library, from `media_player/browse_media`. */
+    async browse(entityId, query) {
+        const client = this.#requireClient();
+        const entity = this.getEntity(entityId);
+        if (entity?.kind !== 'mediaPlayer') {
+            throw new UnknownEntityError(this.id, entityId);
+        }
+        if (query.search !== undefined) {
+            throw new Error('This library cannot be searched');
+        }
+        const at = query.path === undefined ? undefined : decodeItemId(query.path);
+        const level = await client.sendCommand({
+            type: 'media_player/browse_media',
+            entity_id: entityId,
+            ...(at ? { media_content_type: at.contentType, media_content_id: at.contentId } : {}),
+        });
+        return {
+            ...(at && level.title ? { title: level.title } : {}),
+            items: (level.children ?? []).map((media) => toBrowseItem(media, this.#assetUrl)),
+        };
+    }
+    /** Calls any Home Assistant service: `{ domain, service, entityIds?, data? }`. */
+    async callRaw(request) {
+        const { domain, service, entityIds, data } = request;
+        if (typeof domain !== 'string' || typeof service !== 'string') {
+            throw new Error('A raw Home Assistant request needs a "domain" and a "service"');
+        }
+        const ids = Array.isArray(entityIds) ? entityIds.filter((i) => typeof i === 'string') : [];
+        return this.#requireClient().callService(domain, service, data && typeof data === 'object' ? data : undefined, ids.length > 0 ? { entity_id: ids } : undefined);
+    }
+    async getAreas() {
+        return this.#requireClient().sendCommand({ type: 'config/area_registry/list' });
+    }
+    async getEntityRegistry() {
+        return this.#requireClient().sendCommand({
+            type: 'config/entity_registry/list',
+        });
+    }
+    #requireClient() {
+        if (!this.#client) {
+            throw new Error('Home Assistant integration is not connected');
+        }
+        return this.#client;
+    }
+    #applyEntities(entities) {
+        const next = new Map();
+        const nextCache = new Map();
+        const options = {
+            temperatureUnit: this.#options.temperatureUnit ?? '°C',
+            assetUrl: this.#assetUrl,
+        };
+        for (const [id, entity] of Object.entries(entities)) {
+            // The HA lib keeps object identity for unchanged entities; reuse our mapped input so
+            // replaceEntities only notifies subscribers of real changes.
+            const cached = this.#cache.get(id);
+            const entry = cached && cached.source === entity
+                ? cached
+                : { source: entity, input: mapEntity(entity, options) };
+            nextCache.set(id, entry);
+            next.set(id, entry.input);
+        }
+        this.#cache = nextCache;
+        this.replaceEntities(next);
+    }
+}

package/dist/logbook.d.ts

@@ -0,0 +1,28 @@
+import type { LogbookEntry } from '@hashsome/core';
+/** One event of `logbook/get_events`: a change to an entity and, when known, what caused it. Every
+ * field but the time is optional. */
+export interface HaLogbookEvent {
+    /** Seconds since the epoch, with a fraction. */
+    when?: number;
+    entity_id?: string;
+    /** The state it changed to. */
+    state?: string;
+    context_user_id?: string | null;
+    context_event_type?: string | null;
+    context_domain?: string | null;
+    context_name?: string | null;
+    context_entity_id?: string | null;
+}
+/** What the integration knows that an event refers to by id. */
+export interface LogbookLookup {
+    /** The name of the person for a Home Assistant user id (a `person` entity carries it). */
+    personByUserId: ReadonlyMap<string, string>;
+    /** The name of an entity: an automation, a light group. */
+    nameOf: (entityId: string) => string | undefined;
+}
+/** What happened, from the state it changed to. Lowercase, with no actor in front. */
+export declare function messageFor(state: string | undefined): string;
+/** The events as entries, newest first and at most `limit` of them. An event without a usable time is
+ * dropped. A change of state with no cause that follows the device being unreachable is worded as it
+ * coming back ("came back online, on"), not as someone turning it on. */
+export declare function toLogbookEntries(events: readonly HaLogbookEvent[], lookup: LogbookLookup, limit: number): LogbookEntry[];

package/dist/logbook.js

@@ -0,0 +1,78 @@
+/** What happened, from the state it changed to. Lowercase, with no actor in front. */
+export function messageFor(state) {
+    switch (state) {
+        case undefined:
+        case '':
+            return 'changed';
+        case 'on':
+            return 'turned on';
+        case 'off':
+            return 'turned off';
+        case 'unavailable':
+            return 'became unavailable';
+        case 'unknown':
+            return 'became unknown';
+        default:
+            return `changed to ${state}`;
+    }
+}
+/** Who or what caused an event. An automation comes first (it is the more specific cause, even when
+ * someone ran it), then a person by their user id, then another entity that drove it (a light group).
+ * Nobody when nothing says: a device going offline. */
+function actorOf(event, lookup) {
+    const triggeredBy = event.context_entity_id ?? undefined;
+    if (event.context_event_type === 'automation_triggered' ||
+        event.context_domain === 'automation') {
+        const name = event.context_name ?? (triggeredBy ? lookup.nameOf(triggeredBy) : undefined);
+        return name ? { actor: name, actorKind: 'automation' } : {};
+    }
+    const person = event.context_user_id
+        ? lookup.personByUserId.get(event.context_user_id)
+        : undefined;
+    if (person) {
+        return { actor: person, actorKind: 'person' };
+    }
+    if (triggeredBy && triggeredBy !== event.entity_id) {
+        return { actor: lookup.nameOf(triggeredBy) ?? triggeredBy, actorKind: 'automation' };
+    }
+    return {};
+}
+const UNREACHABLE = new Set(['unavailable', 'unknown']);
+/** What kind of change a state is: on, off, the device being (un)reachable, or any other mode. */
+function changeOf(state, back) {
+    if (back || (state !== undefined && UNREACHABLE.has(state))) {
+        return 'availability';
+    }
+    return state === 'on' || state === 'off' ? state : 'state';
+}
+/** The events as entries, newest first and at most `limit` of them. An event without a usable time is
+ * dropped. A change of state with no cause that follows the device being unreachable is worded as it
+ * coming back ("came back online, on"), not as someone turning it on. */
+export function toLogbookEntries(events, lookup, limit) {
+    const lastState = new Map();
+    return events
+        .flatMap((event) => typeof event.when === 'number' && Number.isFinite(event.when)
+        ? [{ event, when: event.when }]
+        : [])
+        .toSorted((a, b) => a.when - b.when)
+        .map(({ event, when }) => {
+        const entity = event.entity_id ?? '';
+        const before = lastState.get(entity);
+        lastState.set(entity, event.state);
+        const cause = actorOf(event, lookup);
+        const back = cause.actor === undefined &&
+            before !== undefined &&
+            UNREACHABLE.has(before) &&
+            event.state !== undefined &&
+            !UNREACHABLE.has(event.state);
+        return {
+            id: `${entity}@${when}`,
+            message: back ? `came back online, ${event.state}` : messageFor(event.state),
+            timestamp: new Date(when * 1000).toISOString(),
+            change: changeOf(event.state, back),
+            ...cause,
+        };
+    })
+        .toReversed()
+        .slice(0, limit);
+}

package/dist/mappers/climate.d.ts

@@ -0,0 +1,6 @@
+import type { ClimateMode, EntityInput } from '@hashsome/core';
+import type { HassEntity } from 'home-assistant-js-websocket';
+/** Home Assistant's HVAC mode names and the model's (camelCase) ones. */
+export declare const HVAC_TO_MODE: Record<string, ClimateMode>;
+export declare const MODE_TO_HVAC: Record<ClimateMode, string>;
+export declare function mapClimate(entity: HassEntity, unit: '°C' | '°F'): EntityInput;

package/dist/mappers/climate.js

@@ -0,0 +1,55 @@
+import { baseOf, num, str, strings } from './common.js';
+/** Home Assistant's HVAC mode names and the model's (camelCase) ones. */
+export const HVAC_TO_MODE = {
+    off: 'off',
+    heat: 'heat',
+    cool: 'cool',
+    auto: 'auto',
+    heat_cool: 'heatCool',
+    dry: 'dry',
+    fan_only: 'fanOnly',
+};
+export const MODE_TO_HVAC = {
+    off: 'off',
+    heat: 'heat',
+    cool: 'cool',
+    auto: 'auto',
+    heatCool: 'heat_cool',
+    dry: 'dry',
+    fanOnly: 'fan_only',
+};
+const ACTION = {
+    off: 'off',
+    idle: 'idle',
+    heating: 'heating',
+    cooling: 'cooling',
+    drying: 'drying',
+    fan: 'fan',
+};
+export function mapClimate(entity, unit) {
+    const a = entity.attributes;
+    const modes = strings(a.hvac_modes).flatMap((m) => (HVAC_TO_MODE[m] ? [HVAC_TO_MODE[m]] : []));
+    const target = num(a.temperature);
+    const current = num(a.current_temperature);
+    const humidity = num(a.current_humidity);
+    const action = ACTION[str(a.hvac_action) ?? ''];
+    const preset = str(a.preset_mode);
+    return {
+        kind: 'climate',
+        ...baseOf(entity),
+        mode: HVAC_TO_MODE[entity.state] ?? 'off',
+        ...(action ? { action } : {}),
+        ...(target !== undefined ? { targetTemperature: target } : {}),
+        ...(current !== undefined ? { currentTemperature: current } : {}),
+        ...(humidity !== undefined ? { humidity } : {}),
+        unit,
+        ...(preset ? { preset } : {}),
+        capabilities: {
+            modes: modes.length > 0 ? modes : ['off', 'heat'],
+            presets: strings(a.preset_modes),
+            targetTemperature: target !== undefined,
+            step: num(a.target_temp_step) ?? 0.5,
+            range: { min: num(a.min_temp) ?? 5, max: num(a.max_temp) ?? 35 },
+        },
+    };
+}

package/dist/mappers/common.d.ts

@@ -0,0 +1,24 @@
+import type { Availability } from '@hashsome/core';
+import type { HassEntity } from 'home-assistant-js-websocket';
+/** The domain of a Home Assistant entity id: `light` for `light.kitchen`. */
+export declare function domainOf(entityId: string): string;
+export declare function availabilityOf(entity: HassEntity): Availability;
+/** A file address in an entity attribute. Home Assistant serves its own files from a path like
+ * `/api/media_player_proxy/…` that only makes sense on Home Assistant, so those go through
+ * `toAssetUrl`; a full address is kept as it is. */
+export declare function fileUrl(value: string, toAssetUrl: (path: string) => string): string;
+export declare function nameOf(entity: HassEntity): string;
+/** What every mapped entity shares: name, availability, timestamps and the untouched payload. */
+export declare function baseOf(entity: HassEntity): {
+    name: string;
+    availability: Availability;
+    lastChanged?: string;
+    lastUpdated?: string;
+    raw: Record<string, unknown>;
+};
+export declare const num: (value: unknown) => number | undefined;
+/** Where the wind comes from in degrees, from what Home Assistant gives: degrees as a number or as
+ * text, or a compass name such as `NNW`. Anything else is nothing. */
+export declare function bearing(value: unknown): number | undefined;
+export declare const str: (value: unknown) => string | undefined;
+export declare const strings: (value: unknown) => string[];

package/dist/mappers/common.js

@@ -0,0 +1,72 @@
+/** The domain of a Home Assistant entity id: `light` for `light.kitchen`. */
+export function domainOf(entityId) {
+    const index = entityId.indexOf('.');
+    return index === -1 ? entityId : entityId.slice(0, index);
+}
+export function availabilityOf(entity) {
+    if (entity.state === 'unavailable') {
+        return 'unavailable';
+    }
+    if (entity.state === 'unknown') {
+        return 'unknown';
+    }
+    return 'ready';
+}
+/** A file address in an entity attribute. Home Assistant serves its own files from a path like
+ * `/api/media_player_proxy/…` that only makes sense on Home Assistant, so those go through
+ * `toAssetUrl`; a full address is kept as it is. */
+export function fileUrl(value, toAssetUrl) {
+    return value.startsWith('/') && !value.startsWith('//') ? toAssetUrl(value) : value;
+}
+export function nameOf(entity) {
+    const name = entity.attributes.friendly_name;
+    return typeof name === 'string' && name ? name : entity.entity_id;
+}
+/** What every mapped entity shares: name, availability, timestamps and the untouched payload. */
+export function baseOf(entity) {
+    return {
+        name: nameOf(entity),
+        availability: availabilityOf(entity),
+        ...(entity.last_changed ? { lastChanged: entity.last_changed } : {}),
+        ...(entity.last_updated ? { lastUpdated: entity.last_updated } : {}),
+        raw: { state: entity.state, attributes: entity.attributes },
+    };
+}
+export const num = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+/** 16-point compass names, by the degrees they start at: a wind from `NNE` comes from 22.5 degrees. */
+const COMPASS = [
+    'N',
+    'NNE',
+    'NE',
+    'ENE',
+    'E',
+    'ESE',
+    'SE',
+    'SSE',
+    'S',
+    'SSW',
+    'SW',
+    'WSW',
+    'W',
+    'WNW',
+    'NW',
+    'NNW',
+];
+/** Where the wind comes from in degrees, from what Home Assistant gives: degrees as a number or as
+ * text, or a compass name such as `NNW`. Anything else is nothing. */
+export function bearing(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return ((value % 360) + 360) % 360;
+    }
+    if (typeof value !== 'string' || value.trim() === '') {
+        return undefined;
+    }
+    const degrees = Number(value);
+    if (Number.isFinite(degrees)) {
+        return ((degrees % 360) + 360) % 360;
+    }
+    const index = COMPASS.indexOf(value.trim().toUpperCase());
+    return index === -1 ? undefined : index * 22.5;
+}
+export const str = (value) => typeof value === 'string' && value ? value : undefined;
+export const strings = (value) => Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];

package/dist/mappers/index.d.ts

@@ -0,0 +1,14 @@
+import type { EntityInput } from '@hashsome/core';
+import type { HassEntity } from 'home-assistant-js-websocket';
+export interface MapOptions {
+    /** Home Assistant reports the temperature unit in its own config, not per entity. */
+    temperatureUnit: '°C' | '°F';
+    /** Turns a path on Home Assistant into an address the browser can load. Defaults to leaving it. */
+    assetUrl?: (path: string) => string;
+}
+/** Domains that are something to trigger, not something with a state to read. */
+export declare const ACTION_DOMAINS: string[];
+/** Domains with two states that can be flipped (a lock is "on" while locked). */
+export declare const SWITCH_DOMAINS: string[];
+/** Maps a Home Assistant entity to the generic model (everything but `ref`). Pure. */
+export declare function mapEntity(entity: HassEntity, options: MapOptions): EntityInput;

package/dist/mappers/index.js

@@ -0,0 +1,37 @@
+import { domainOf } from './common.js';
+import { mapClimate } from './climate.js';
+import { mapLight } from './light.js';
+import { mapMediaPlayer } from './media-player.js';
+import { mapWeather } from './weather.js';
+import { mapAction, mapGeneric, mapPerson, mapSensor, mapSwitch } from './simple.js';
+/** Domains that are something to trigger, not something with a state to read. */
+export const ACTION_DOMAINS = ['scene', 'script', 'button', 'input_button', 'automation', 'vacuum'];
+/** Domains with two states that can be flipped (a lock is "on" while locked). */
+export const SWITCH_DOMAINS = ['switch', 'fan', 'input_boolean', 'lock'];
+/** Maps a Home Assistant entity to the generic model (everything but `ref`). Pure. */
+export function mapEntity(entity, options) {
+    const domain = domainOf(entity.entity_id);
+    switch (domain) {
+        case 'media_player':
+            return mapMediaPlayer(entity, options.assetUrl);
+        case 'light':
+            return mapLight(entity);
+        case 'climate':
+            return mapClimate(entity, options.temperatureUnit);
+        case 'sensor':
+        case 'binary_sensor':
+            return mapSensor(entity);
+        case 'person':
+            return mapPerson(entity, options.assetUrl);
+        case 'weather':
+            return mapWeather(entity);
+        default:
+            if (SWITCH_DOMAINS.includes(domain)) {
+                return mapSwitch(entity);
+            }
+            if (ACTION_DOMAINS.includes(domain)) {
+                return mapAction(entity);
+            }
+            return mapGeneric(entity);
+    }
+}

package/dist/mappers/light.d.ts

@@ -0,0 +1,3 @@
+import type { EntityInput } from '@hashsome/core';
+import type { HassEntity } from 'home-assistant-js-websocket';
+export declare function mapLight(entity: HassEntity): EntityInput;