@hashsome/core 0.1.0 → 0.2.0

package/dist/client.js

@@ -101,6 +101,24 @@ export class RemoteClient {
             args: { ...query },
         })));
     }
+    async forecast(ref, query) {
+        return (await this.#request((id) => ({
+            type: 'query',
+            id,
+            ref,
+            query: 'forecast',
+            args: { ...query },
+        })));
+    }
+    async logbook(ref, query) {
+        return (await this.#request((id) => ({
+            type: 'query',
+            id,
+            ref,
+            query: 'logbook',
+            args: { ...query },
+        })));
+    }
     callRaw(integration, request) {
         return this.#request((id) => ({ type: 'raw', id, integration, request }));
     }

package/dist/integration.d.ts

@@ -1,5 +1,5 @@
 import type { EntityRef } from './entity.ts';
-import type { BrowseQuery, BrowseResult, Entity, HistoryQuery, HistoryResult } from './model/index.ts';
+import type { BrowseQuery, BrowseResult, Entity, ForecastQuery, ForecastResult, HistoryQuery, HistoryResult, LogbookQuery, LogbookResult } from './model/index.ts';
 export type ConnectionStatus = 'connecting' | 'connected' | 'disconnected' | 'error';
 export type Unsubscribe = () => void;
 /**
@@ -48,6 +48,20 @@ export interface Integration {
      * Arguments come from a browser: validate them.
      */
     history?(entityId: string, query: HistoryQuery): Promise<HistoryResult>;
+    /**
+     * A weather entity's forecast of the asked kind (days, hours, half-days), soonest first. Optional:
+     * only for backends that have forecasts. Resolves with no points when the entity cannot give that
+     * kind, and rejects with a displayable `Error` for an unknown entity. Arguments come from a
+     * browser: validate them.
+     */
+    forecast?(entityId: string, query: ForecastQuery): Promise<ForecastResult>;
+    /**
+     * Recent activity of an entity: what happened to it (turned on, went offline) and who or what
+     * caused it, newest first. Optional: only for backends that keep such a record (Home Assistant's
+     * logbook). Resolves with no entries for an entity with none, and rejects with a displayable
+     * `Error` for an unknown entity. Arguments come from a browser: validate them.
+     */
+    logbook?(entityId: string, query: LogbookQuery): Promise<LogbookResult>;
     /**
      * Fetches a file the backend serves for its entities, such as artwork, with the integration's own
      * credentials. `path` is the backend's own path and starts with `/`; it comes from a browser, so

package/dist/local-client.d.ts

@@ -1,7 +1,7 @@
 import type { Client, EntityListener, LinkStatus } from './client.ts';
 import { type EntityRef } from './entity.ts';
 import type { ConnectionStatus, Integration, Unsubscribe } from './integration.ts';
-import type { BrowseQuery, BrowseResult, Entity, HistoryQuery, HistoryResult } from './model/index.ts';
+import type { BrowseQuery, BrowseResult, Entity, ForecastQuery, ForecastResult, HistoryQuery, HistoryResult, LogbookQuery, LogbookResult } from './model/index.ts';
 /** In-process `Client` over integrations, with no runtime server. Used by the gallery and tests. */
 export declare class LocalClient implements Client {
     #private;
@@ -18,5 +18,7 @@ export declare class LocalClient implements Client {
     command(ref: EntityRef, name: string, args?: Record<string, unknown>): Promise<void>;
     browse(ref: EntityRef, query: BrowseQuery): Promise<BrowseResult>;
     history(ref: EntityRef, query: HistoryQuery): Promise<HistoryResult>;
+    forecast(ref: EntityRef, query: ForecastQuery): Promise<ForecastResult>;
+    logbook(ref: EntityRef, query: LogbookQuery): Promise<LogbookResult>;
     callRaw(integration: string, request: Record<string, unknown>): Promise<unknown>;
 }

package/dist/local-client.js

@@ -99,6 +99,28 @@ export class LocalClient {
         }
         return source.history(id, query);
     }
+    forecast(ref, query) {
+        const { integration, id } = parseEntityRef(ref);
+        const source = this.#integrations.get(integration);
+        if (!source) {
+            return Promise.reject(new Error(`Unknown integration "${integration}"`));
+        }
+        if (!source.forecast) {
+            return Promise.reject(new Error(`"${integration}" has no forecasts`));
+        }
+        return source.forecast(id, query);
+    }
+    logbook(ref, query) {
+        const { integration, id } = parseEntityRef(ref);
+        const source = this.#integrations.get(integration);
+        if (!source) {
+            return Promise.reject(new Error(`Unknown integration "${integration}"`));
+        }
+        if (!source.logbook) {
+            return Promise.reject(new Error(`"${integration}" keeps no activity`));
+        }
+        return source.logbook(id, query);
+    }
     callRaw(integration, request) {
         const source = this.#integrations.get(integration);
         if (!source) {

package/dist/mock-forecast.d.ts

@@ -0,0 +1,8 @@
+import type { Entity, ForecastQuery, ForecastResult } from './model/index.ts';
+/**
+ * A made-up but believable forecast for a mock weather entity, so the UI that a real source feeds
+ * has something to show: a spell of weather moving through, warmer afternoons and colder nights
+ * around the entity's current temperature. The same every time for the same entity and moment (`now`
+ * is a parameter so a test can pin it). Anything that is not a weather entity has none.
+ */
+export declare function mockForecast(entity: Entity | undefined, query: ForecastQuery, now?: number): ForecastResult;

package/dist/mock-forecast.js

@@ -0,0 +1,136 @@
+const HOUR = 3_600_000;
+const DAY = 24 * HOUR;
+/** A spell of weather the made-up days run through, so a forecast is not one flat condition. */
+const SPELL = [
+    'sunny',
+    'partlycloudy',
+    'cloudy',
+    'rainy',
+    'pouring',
+    'partlycloudy',
+    'sunny',
+    'sunny',
+    'cloudy',
+    'fog',
+];
+/** How likely rain is under each condition, percent. */
+const RAIN = {
+    cloudy: 15,
+    fog: 10,
+    rainy: 70,
+    pouring: 95,
+    'lightning-rainy': 90,
+    'snowy-rainy': 80,
+};
+/** How much of the sky is cloud under each condition, percent. */
+const CLOUD = {
+    sunny: 4,
+    'clear-night': 4,
+    partlycloudy: 50,
+    cloudy: 90,
+    fog: 100,
+    rainy: 95,
+    pouring: 100,
+    'lightning-rainy': 100,
+};
+const STEPS = { daily: 10, hourly: 48, twice_daily: 14 };
+const round = (value) => Math.round(value * 10) / 10;
+/**
+ * A made-up but believable forecast for a mock weather entity, so the UI that a real source feeds
+ * has something to show: a spell of weather moving through, warmer afternoons and colder nights
+ * around the entity's current temperature. The same every time for the same entity and moment (`now`
+ * is a parameter so a test can pin it). Anything that is not a weather entity has none.
+ */
+export function mockForecast(entity, query, now = Date.now()) {
+    if (entity?.kind !== 'weather') {
+        return { type: query.type, points: [] };
+    }
+    const base = entity.temperature ?? 15;
+    const start = new Date(now);
+    const points = [];
+    // The wind swings round slowly and gusts up with the rain.
+    const wind = (step) => entity.windSpeed === undefined
+        ? {}
+        : {
+            windSpeed: round(entity.windSpeed * (0.7 + 0.6 * Math.abs(Math.sin(step * 0.7)))),
+            windBearing: Math.round(((entity.windBearing ?? 0) + step * 9) % 360),
+        };
+    const spellAt = (step) => SPELL[(step + Math.max(0, SPELL.indexOf(entity.condition))) % SPELL.length];
+    if (query.type === 'hourly') {
+        start.setMinutes(0, 0, 0);
+        for (let i = 0; i < STEPS.hourly; i += 1) {
+            const time = new Date(start.getTime() + i * HOUR);
+            const hours = time.getHours();
+            const condition = spellAt(Math.floor(i / 8));
+            const night = hours < 6 || hours >= 21;
+            points.push({
+                timestamp: time.toISOString(),
+                condition: night && condition === 'sunny' ? 'clear-night' : condition,
+                temperature: round(base + 4 * Math.sin(((hours - 9) / 24) * 2 * Math.PI) - i * 0.05),
+                precipitationProbability: RAIN[condition] ?? 0,
+                ...wind(i),
+            });
+        }
+    }
+    else if (query.type === 'twice_daily') {
+        start.setHours(0, 0, 0, 0);
+        for (let i = 0; i < STEPS.twice_daily; i += 1) {
+            const daytime = i % 2 === 0;
+            const condition = spellAt(Math.floor(i / 2));
+            points.push({
+                timestamp: new Date(start.getTime() + i * 12 * HOUR + (daytime ? 6 * HOUR : 0)).toISOString(),
+                condition: !daytime && condition === 'sunny' ? 'clear-night' : condition,
+                temperature: round(daytime ? base + 4 + Math.sin(i) : base - 4 + Math.sin(i)),
+                precipitationProbability: RAIN[condition] ?? 0,
+                daytime,
+                ...wind(i),
+            });
+        }
+    }
+    else {
+        start.setHours(0, 0, 0, 0);
+        for (let i = 0; i < STEPS.daily; i += 1) {
+            const condition = spellAt(i);
+            const drift = 2 * Math.sin(i * 1.3);
+            points.push({
+                timestamp: new Date(start.getTime() + i * DAY).toISOString(),
+                condition,
+                temperature: round(base + 3 + drift),
+                low: round(base - 5 + drift),
+                precipitationProbability: RAIN[condition] ?? 0,
+                ...(RAIN[condition] ? { precipitation: round((RAIN[condition] ?? 0) / 12) } : {}),
+                ...wind(i),
+            });
+        }
+    }
+    // What else a weather source gives for a step, made up from the step itself: it is more humid when
+    // cold and cloudy, the sun peaks at noon (or at its day's best, for a whole day) and is dimmed by cloud,
+    // and gusts and the feels-like follow the wind.
+    const enrich = (point) => {
+        const cloud = CLOUD[point.condition] ?? 50;
+        const temperature = point.temperature ?? base;
+        const hour = new Date(point.timestamp).getHours();
+        const sun = query.type === 'daily' ? 1 : Math.max(0, Math.sin(((hour - 6) / 12) * Math.PI));
+        const rain = RAIN[point.condition] ?? 0;
+        return {
+            ...point,
+            humidity: Math.min(100, Math.max(20, Math.round(85 - (temperature - 5) * 2 + cloud * 0.1))),
+            cloudCoverage: cloud,
+            uvIndex: point.daytime === false ? 0 : round(sun * 8 * (1 - cloud / 140)),
+            apparentTemperature: round(temperature - 1 - (point.windSpeed ?? 0) * 0.05),
+            pressure: Math.round(1015 - rain * 0.12 + Math.sin(hour / 4)),
+            ...(point.windSpeed !== undefined ? { windGustSpeed: round(point.windSpeed * 1.6) } : {}),
+            ...(rain > 50 && point.precipitation === undefined
+                ? { precipitation: round(rain / 70) }
+                : {}),
+        };
+    };
+    return {
+        type: query.type,
+        points: points.map(enrich),
+        ...(entity.unit ? { unit: entity.unit } : {}),
+        ...(entity.precipitationUnit ? { precipitationUnit: entity.precipitationUnit } : {}),
+        ...(entity.pressureUnit ? { pressureUnit: entity.pressureUnit } : {}),
+        ...(entity.windUnit ? { windUnit: entity.windUnit } : {}),
+    };
+}

package/dist/mock-history.d.ts

@@ -0,0 +1,9 @@
+import type { Entity, HistoryQuery, HistoryResult } from './model/index.ts';
+/**
+ * Made-up but believable history for a numeric mock sensor, so the charts a real backend would fill
+ * have something to show: a daily rhythm (more in the evening), a slower drift over the days and a
+ * little jitter. A reading (a temperature, power) hovers around the sensor's current value; an
+ * `energy` counter (kWh or Wh) answers with how much it grew in each bucket. Nothing else has any.
+ * `now` is a parameter so a test can pin it.
+ */
+export declare function mockHistory(entityId: string, entity: Entity | undefined, query: HistoryQuery, now?: number): HistoryResult;

package/dist/mock-history.js

@@ -0,0 +1,65 @@
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const SPAN = { '1h': HOUR, '1d': DAY, '1w': 7 * DAY, '1m': 30 * DAY };
+const BUCKET = { '5m': 5 * MINUTE, '1h': HOUR, '1d': DAY };
+const DEFAULT_BUCKET = {
+    '1h': '5m',
+    '1d': '5m',
+    '1w': '1h',
+    '1m': '1h',
+};
+/** A number in [0, 1) that is the same for the same text, so a mock device always has the same past. */
+function seed(text) {
+    let hash = 0;
+    for (const char of text) {
+        hash = (hash * 31 + char.codePointAt(0)) % 100_003;
+    }
+    return hash / 100_003;
+}
+const round = (value, digits) => {
+    const factor = 10 ** digits;
+    return Math.round(value * factor) / factor;
+};
+/**
+ * Made-up but believable history for a numeric mock sensor, so the charts a real backend would fill
+ * have something to show: a daily rhythm (more in the evening), a slower drift over the days and a
+ * little jitter. A reading (a temperature, power) hovers around the sensor's current value; an
+ * `energy` counter (kWh or Wh) answers with how much it grew in each bucket. Nothing else has any.
+ * `now` is a parameter so a test can pin it.
+ */
+export function mockHistory(entityId, entity, query, now = Date.now()) {
+    if (entity?.kind !== 'sensor' || entity.numeric === undefined) {
+        return { points: [], kind: 'measurement' };
+    }
+    const total = entity.measurement === 'energy' || entity.unit === 'kWh' || entity.unit === 'Wh';
+    const bucket = BUCKET[query.bucket ?? DEFAULT_BUCKET[query.range]];
+    const count = Math.ceil(SPAN[query.range] / bucket);
+    const end = Math.floor(now / bucket) * bucket;
+    const phase = seed(entityId);
+    // How busy the device is at a time: 0 to 1.
+    const level = (time) => {
+        const hours = (time % DAY) / HOUR;
+        const daily = 0.5 + 0.5 * Math.sin(((hours - 9) / 24) * 2 * Math.PI);
+        const drift = 0.15 * Math.sin((time / DAY) * 1.3 + phase * 6);
+        const jitter = 0.015 * Math.sin((time / bucket) * 1.7 + phase * 9);
+        return Math.min(1, Math.max(0, daily + drift + jitter));
+    };
+    // What a counter grows by in a day: about 0.6 to 1.8 kWh, and the same in Wh.
+    const perDay = (0.6 + 1.2 * phase) * (entity.unit === 'Wh' ? 1000 : 1);
+    const points = [];
+    for (let i = count - 1; i >= 0; i -= 1) {
+        const start = end - i * bucket;
+        points.push({
+            timestamp: new Date(start).toISOString(),
+            value: total
+                ? round((perDay / 24) * (bucket / HOUR) * (0.4 + 1.2 * level(start)), 3)
+                : round(entity.numeric * (0.55 + 0.9 * level(start)), 1),
+        });
+    }
+    return {
+        points,
+        kind: total ? 'total' : 'measurement',
+        ...(entity.unit ? { unit: entity.unit } : {}),
+    };
+}

package/dist/mock-logbook.d.ts

@@ -0,0 +1,8 @@
+import type { Entity, LogbookQuery, LogbookResult } from './model/index.ts';
+/**
+ * Made-up but believable activity for a mock light, switch or heater, so the History section of its
+ * drawer has something to show: it turns on and off through the past days, caused by a person or an
+ * automation, now and then going offline by itself. The same every time for the same entity and
+ * moment (`now` is a parameter so a test can pin it). Anything else has none.
+ */
+export declare function mockLogbook(entityId: string, entity: Entity | undefined, query: LogbookQuery, now?: number): LogbookResult;

package/dist/mock-logbook.js

@@ -0,0 +1,43 @@
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+/** Who the made-up activity is caused by: two people at home, and two automations. */
+const ACTORS = [
+    { actor: 'Dan' },
+    { actor: 'Bedtime', actorKind: 'automation' },
+    { actor: 'Alex' },
+    { actor: 'Sunrise', actorKind: 'automation' },
+    {},
+];
+/** The kinds of entity that switch on and off, and so have activity worth showing. */
+const SWITCHING = new Set(['light', 'switch', 'climate']);
+/**
+ * Made-up but believable activity for a mock light, switch or heater, so the History section of its
+ * drawer has something to show: it turns on and off through the past days, caused by a person or an
+ * automation, now and then going offline by itself. The same every time for the same entity and
+ * moment (`now` is a parameter so a test can pin it). Anything else has none.
+ */
+export function mockLogbook(entityId, entity, query, now = Date.now()) {
+    if (!entity || !SWITCHING.has(entity.kind)) {
+        return { entries: [] };
+    }
+    const limit = Math.max(1, Math.min(query.limit ?? 20, 100));
+    const entries = [];
+    let on = entity.kind === 'light' ? entity.on === true : true;
+    for (let i = 0; i < limit; i += 1) {
+        // Further back and a little irregular, newest first.
+        const at = now - (i + 1) * 3 * HOUR - ((i * 7919) % 50) * MINUTE;
+        const cause = ACTORS[(i + entityId.length) % ACTORS.length];
+        const lost = i % 9 === 8;
+        entries.push({
+            id: `${entityId}@${at}`,
+            message: lost ? 'became unavailable' : on ? 'turned on' : 'turned off',
+            timestamp: new Date(at).toISOString(),
+            change: lost ? 'availability' : on ? 'on' : 'off',
+            ...(lost ? {} : cause),
+        });
+        if (!lost) {
+            on = !on;
+        }
+    }
+    return { entries };
+}

package/dist/mock.d.ts

@@ -1,5 +1,5 @@
 import { BaseIntegration } from './base-integration.ts';
-import { type ActionEntity, type BrowseItem, type BrowseQuery, type BrowseResult, type ClimateEntity, type EntityInput, type GenericEntity, type LightEntity, type MediaPlayerEntity, type PersonEntity, type SensorEntity, type SwitchEntity, type WeatherEntity } from './model/index.ts';
+import { type ActionEntity, type BrowseItem, type BrowseQuery, type BrowseResult, type ClimateEntity, type EntityInput, type ForecastQuery, type ForecastResult, type GenericEntity, type HistoryQuery, type HistoryResult, type LogbookQuery, type LogbookResult, type LightEntity, type MediaPlayerEntity, type PersonEntity, type SensorEntity, type SwitchEntity, type WeatherEntity } from './model/index.ts';
 type Init<E extends {
     kind: string;
     ref: unknown;
@@ -55,6 +55,12 @@ export declare class MockIntegration extends BaseIntegration {
     set(entityId: string, input: EntityInput): void;
     /** Patches an entity: top-level fields are replaced, `capabilities` and `media` are merged. */
     update(entityId: string, patch: Partial<EntityInput>): void;
+    /** Made-up history for a numeric sensor (see `mockHistory`); empty for anything else. */
+    history(entityId: string, query: HistoryQuery): Promise<HistoryResult>;
+    /** Made-up activity for a light, switch or heater (see `mockLogbook`); empty for anything else. */
+    logbook(entityId: string, query: LogbookQuery): Promise<LogbookResult>;
+    /** Made-up forecast for a weather entity (see `mockForecast`); empty for anything else. */
+    forecast(entityId: string, query: ForecastQuery): Promise<ForecastResult>;
     browse(entityId: string, query: BrowseQuery): Promise<BrowseResult>;
     command(entityId: string, name: string, args?: Record<string, unknown>): Promise<void>;
 }

package/dist/mock.js

@@ -1,5 +1,8 @@
 import { BaseIntegration } from './base-integration.js';
 import { UnknownEntityError } from './entity.js';
+import { mockForecast } from './mock-forecast.js';
+import { mockHistory } from './mock-history.js';
+import { mockLogbook } from './mock-logbook.js';
 import { isCommandOf, } from './model/index.js';
 export function mockMediaPlayer(init = {}) {
     const { capabilities, ...rest } = init;
@@ -95,6 +98,16 @@ export function mockWeather(init = {}) {
         condition: 'sunny',
         temperature: 20,
         unit: '°C',
+        windSpeed: 14,
+        windBearing: 225,
+        windUnit: 'km/h',
+        uvIndex: 3,
+        cloudCoverage: 40,
+        apparentTemperature: 18,
+        pressure: 1015,
+        pressureUnit: 'hPa',
+        precipitationUnit: 'mm',
+        forecasts: ['daily', 'hourly'],
         ...init,
     };
 }
@@ -377,6 +390,30 @@ export class MockIntegration extends BaseIntegration {
         }
         this.set(entityId, merged);
     }
+    /** Made-up history for a numeric sensor (see `mockHistory`); empty for anything else. */
+    history(entityId, query) {
+        const entity = this.getEntity(entityId);
+        if (!entity) {
+            return Promise.reject(new UnknownEntityError(this.id, entityId));
+        }
+        return Promise.resolve(mockHistory(entityId, entity, query));
+    }
+    /** Made-up activity for a light, switch or heater (see `mockLogbook`); empty for anything else. */
+    logbook(entityId, query) {
+        const entity = this.getEntity(entityId);
+        if (!entity) {
+            return Promise.reject(new UnknownEntityError(this.id, entityId));
+        }
+        return Promise.resolve(mockLogbook(entityId, entity, query));
+    }
+    /** Made-up forecast for a weather entity (see `mockForecast`); empty for anything else. */
+    forecast(entityId, query) {
+        const entity = this.getEntity(entityId);
+        if (!entity) {
+            return Promise.reject(new UnknownEntityError(this.id, entityId));
+        }
+        return Promise.resolve(mockForecast(entity, query));
+    }
     browse(entityId, query) {
         if (!this.getEntity(entityId)) {
             return Promise.reject(new UnknownEntityError(this.id, entityId));

package/dist/model/index.d.ts

@@ -10,6 +10,7 @@ import type { WeatherCommands, WeatherEntity } from './weather.ts';
 export * from './base.ts';
 export * from './browse.ts';
 export * from './history.ts';
+export * from './logbook.ts';
 export * from './action.ts';
 export * from './climate.ts';
 export * from './generic.ts';

package/dist/model/index.js

@@ -1,6 +1,7 @@
 export * from './base.js';
 export * from './browse.js';
 export * from './history.js';
+export * from './logbook.js';
 export * from './action.js';
 export * from './climate.js';
 export * from './generic.js';

package/dist/model/logbook.d.ts

@@ -0,0 +1,26 @@
+/** One thing that happened to an entity: it turned on, went offline, ... and what or who caused it. */
+export interface LogbookEntry {
+    id: string;
+    /** Lowercase, no actor prefix, e.g. "turned on", "became unavailable": capitalized when there is
+     * no `actor` to lead with ("Turned on"), left lowercase after one ("Dan turned on"). */
+    message: string;
+    /** ISO 8601. */
+    timestamp: string;
+    /** Who or what caused it, e.g. "Dan" or "Bedtime". Omitted when it was the system (a device going offline). */
+    actor?: string;
+    /** Only matters when `actor` is set: a person gets an initials avatar, an automation (or anything
+     * else that is not a person) a workflow icon. Default `'person'`. */
+    actorKind?: 'person' | 'automation';
+    /** What kind of change it was: it turned `on` or `off`, took another `state` (a new mode), or its
+     * `availability` changed (the device could not be reached, or came back). Lets a row say more than
+     * the words when nothing caused it: an on or off with no actor is often someone at a physical switch. */
+    change?: 'on' | 'off' | 'state' | 'availability';
+}
+export interface LogbookQuery {
+    /** How many of the latest entries to return. Default 20. */
+    limit?: number;
+}
+export interface LogbookResult {
+    /** Newest first; empty when the backend keeps no activity for the entity. */
+    entries: LogbookEntry[];
+}

package/dist/model/logbook.js

@@ -0,0 +1 @@
+export {};

package/dist/model/weather.d.ts

@@ -3,6 +3,10 @@ import type { EntityBase } from './base.ts';
  * reports that is not one of these is `unknown`. */
 export declare const WEATHER_CONDITIONS: readonly ['sunny', 'clear-night', 'partlycloudy', 'cloudy', 'fog', 'rainy', 'pouring', 'snowy', 'snowy-rainy', 'hail', 'lightning', 'lightning-rainy', 'windy', 'exceptional', 'unknown'];
 export type WeatherCondition = (typeof WEATHER_CONDITIONS)[number];
+/** What a forecast looks ahead in: `daily` is a day per point, `hourly` an hour, and `twice_daily` a
+ * day and a night. A weather source supports some of them. */
+export declare const FORECAST_TYPES: readonly ['daily', 'hourly', 'twice_daily'];
+export type ForecastType = (typeof FORECAST_TYPES)[number];
 /** Current weather for a place. */
 export interface WeatherEntity extends EntityBase<'weather'> {
     condition: WeatherCondition;
@@ -12,5 +16,73 @@ export interface WeatherEntity extends EntityBase<'weather'> {
     unit?: string;
     /** Percent. */
     humidity?: number;
+    /** How hard the wind blows, in `windUnit`. */
+    windSpeed?: number;
+    /** Where the wind comes from, in degrees: 0 is north, 90 east. */
+    windBearing?: number;
+    /** `km/h`, `mph`, `m/s`, ... */
+    windUnit?: string;
+    /** UV index: 0 to 11 and more. */
+    uvIndex?: number;
+    /** Percent of the sky covered by cloud. */
+    cloudCoverage?: number;
+    /** What it feels like, in `unit`: the temperature with the wind and humidity counted in. */
+    apparentTemperature?: number;
+    /** Air pressure, in `pressureUnit`. */
+    pressure?: number;
+    /** `hPa`, `inHg`, ... */
+    pressureUnit?: string;
+    /** `mm` or `in`: the unit of the rain a forecast gives. */
+    precipitationUnit?: string;
+    /** The forecasts the weather source can give, if any. Ask for one with `Client.forecast`. */
+    forecasts?: ForecastType[];
+}
+export interface ForecastQuery {
+    type: ForecastType;
+}
+/** One step of a forecast: a day, an hour, or half a day. */
+export interface ForecastPoint {
+    /** When the step starts, ISO 8601. */
+    timestamp: string;
+    condition: WeatherCondition;
+    /** The temperature, or the day's high; in the result's `unit`. */
+    temperature?: number;
+    /** The day's low, for a forecast that covers a whole day. */
+    low?: number;
+    /** Percent chance of rain or snow. */
+    precipitationProbability?: number;
+    /** Expected rain or snow, in the result's `precipitationUnit`. */
+    precipitation?: number;
+    /** In the result's `windUnit`. */
+    windSpeed?: number;
+    /** Where the wind comes from, in degrees: 0 is north, 90 east. */
+    windBearing?: number;
+    /** The strongest gusts, in the result's `windUnit`. */
+    windGustSpeed?: number;
+    /** Percent. */
+    humidity?: number;
+    /** Percent of the sky covered by cloud. */
+    cloudCoverage?: number;
+    /** UV index. */
+    uvIndex?: number;
+    /** What it feels like, in the result's `unit`. */
+    apparentTemperature?: number;
+    /** Air pressure, in the result's `pressureUnit`. */
+    pressure?: number;
+    /** For `twice_daily`: whether this step is the day (true) or the night. */
+    daytime?: boolean;
+}
+export interface ForecastResult {
+    type: ForecastType;
+    /** Soonest first; empty when the source has no forecast of that type. */
+    points: ForecastPoint[];
+    /** `°C` or `°F`. */
+    unit?: string;
+    /** The unit of `windSpeed`: `km/h`, `mph`, ... */
+    windUnit?: string;
+    /** The unit of `precipitation`: `mm` or `in`. */
+    precipitationUnit?: string;
+    /** The unit of `pressure`: `hPa`, `inHg`, ... */
+    pressureUnit?: string;
 }
 export type WeatherCommands = Record<string, never>;

package/dist/model/weather.js

@@ -17,3 +17,6 @@ export const WEATHER_CONDITIONS = [
     'exceptional',
     'unknown',
 ];
+/** What a forecast looks ahead in: `daily` is a day per point, `hourly` an hour, and `twice_daily` a
+ * day and a night. A weather source supports some of them. */
+export const FORECAST_TYPES = ['daily', 'hourly', 'twice_daily'];

package/dist/protocol.d.ts

@@ -22,11 +22,11 @@ export type ClientMessage = {
     command: string;
     args?: Record<string, unknown>;
 } | {
-    /** A read that is not a subscription: one level of a media library, or an entity's history, answered by `result`. */
+    /** A read that is not a subscription: one level of a media library, an entity's history, a weather forecast, or its recent activity, answered by `result`. */
     type: 'query';
     id: number;
     ref: EntityRef;
-    query: 'browse' | 'history';
+    query: 'browse' | 'history' | 'forecast' | 'logbook';
     args?: Record<string, unknown>;
 } | {
     type: 'raw';

package/dist/protocol.js

@@ -42,7 +42,10 @@ export function parseClientMessage(raw) {
         case 'query': {
             if (typeof value.id !== 'number' ||
                 !isRef(value.ref) ||
-                (value.query !== 'browse' && value.query !== 'history') ||
+                (value.query !== 'browse' &&
+                    value.query !== 'history' &&
+                    value.query !== 'forecast' &&
+                    value.query !== 'logbook') ||
                 (value.args !== undefined && !isRecord(value.args))) {
                 return undefined;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashsome/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Framework-agnostic integration interface, entity types and wire protocol (no vendor-specific code)",
   "type": "module",
   "exports": {

package/dist/base-integration.js.map

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