@hashsome/core 0.1.0

package/dist/integration.js.map

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

package/dist/local-client.d.ts

@@ -0,0 +1,22 @@
+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';
+/** In-process `Client` over integrations, with no runtime server. Used by the gallery and tests. */
+export declare class LocalClient implements Client {
+    #private;
+    constructor(integrations: Integration[]);
+    get link(): LinkStatus;
+    connect(): void;
+    close(): void;
+    onLinkChange(listener: (status: LinkStatus) => void): Unsubscribe;
+    getIntegrationStatus(integration: string): ConnectionStatus | undefined;
+    getIntegrationStatuses(): Readonly<Record<string, ConnectionStatus>>;
+    onIntegrationStatusChange(listener: () => void): Unsubscribe;
+    getEntity(ref: EntityRef): Entity | null;
+    subscribe(ref: EntityRef, listener: EntityListener): Unsubscribe;
+    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>;
+    callRaw(integration: string, request: Record<string, unknown>): Promise<unknown>;
+}

package/dist/local-client.js

@@ -0,0 +1,121 @@
+import { parseEntityRef, UnknownEntityError } from './entity.js';
+/** In-process `Client` over integrations, with no runtime server. Used by the gallery and tests. */
+export class LocalClient {
+    #integrations = new Map();
+    #link = 'closed';
+    #linkListeners = new Set();
+    #statusSnapshot = {};
+    constructor(integrations) {
+        for (const integration of integrations) {
+            this.#integrations.set(integration.id, integration);
+        }
+    }
+    get link() {
+        return this.#link;
+    }
+    connect() {
+        if (this.#link === 'open') {
+            return;
+        }
+        this.#setLink('open');
+        for (const integration of this.#integrations.values()) {
+            void integration.connect();
+        }
+    }
+    close() {
+        this.#setLink('closed');
+    }
+    onLinkChange(listener) {
+        this.#linkListeners.add(listener);
+        return () => {
+            this.#linkListeners.delete(listener);
+        };
+    }
+    getIntegrationStatus(integration) {
+        return this.#integrations.get(integration)?.status;
+    }
+    getIntegrationStatuses() {
+        const next = Object.fromEntries([...this.#integrations.values()].map((i) => [i.id, i.status]));
+        const same = Object.keys(next).length === Object.keys(this.#statusSnapshot).length &&
+            Object.entries(next).every(([id, status]) => this.#statusSnapshot[id] === status);
+        if (!same) {
+            this.#statusSnapshot = next;
+        }
+        return this.#statusSnapshot;
+    }
+    onIntegrationStatusChange(listener) {
+        const offs = [...this.#integrations.values()].map((i) => i.onStatusChange(listener));
+        return () => offs.forEach((off) => off());
+    }
+    getEntity(ref) {
+        const { integration, id } = parseEntityRef(ref);
+        return this.#integrations.get(integration)?.getEntity(id) ?? null;
+    }
+    subscribe(ref, listener) {
+        const { integration, id } = parseEntityRef(ref);
+        const source = this.#integrations.get(integration);
+        if (!source) {
+            listener(null);
+            return () => { };
+        }
+        try {
+            return source.subscribe(id, (entity) => listener(entity ?? null));
+        }
+        catch (error) {
+            if (error instanceof UnknownEntityError) {
+                listener(null);
+                return () => { };
+            }
+            throw error;
+        }
+    }
+    command(ref, name, args) {
+        const { integration, id } = parseEntityRef(ref);
+        const source = this.#integrations.get(integration);
+        if (!source) {
+            return Promise.reject(new Error(`Unknown integration "${integration}"`));
+        }
+        return source.command(id, name, args);
+    }
+    browse(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.browse) {
+            return Promise.reject(new Error(`"${integration}" has no media library`));
+        }
+        return source.browse(id, query);
+    }
+    history(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.history) {
+            return Promise.reject(new Error(`"${integration}" keeps no history`));
+        }
+        return source.history(id, query);
+    }
+    callRaw(integration, request) {
+        const source = this.#integrations.get(integration);
+        if (!source) {
+            return Promise.reject(new Error(`Unknown integration "${integration}"`));
+        }
+        if (!source.callRaw) {
+            return Promise.reject(new Error(`Integration "${integration}" has no raw requests`));
+        }
+        return source.callRaw(request);
+    }
+    #setLink(status) {
+        if (status === this.#link) {
+            return;
+        }
+        this.#link = status;
+        for (const listener of Array.from(this.#linkListeners)) {
+            listener(status);
+        }
+    }
+}

package/dist/local-client.js.map

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

package/dist/mock.d.ts

@@ -0,0 +1,61 @@
+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';
+type Init<E extends {
+    kind: string;
+    ref: unknown;
+}, K extends keyof E = never> = Partial<Omit<E, 'ref' | 'kind' | K>>;
+export declare function mockMediaPlayer(init?: Init<MediaPlayerEntity, 'capabilities'> & {
+    capabilities?: Partial<MediaPlayerEntity['capabilities']>;
+}): EntityInput;
+export declare function mockLight(init?: Init<LightEntity, 'capabilities'> & {
+    capabilities?: Partial<LightEntity['capabilities']>;
+}): EntityInput;
+export declare function mockClimate(init?: Init<ClimateEntity, 'capabilities'> & {
+    capabilities?: Partial<ClimateEntity['capabilities']>;
+}): EntityInput;
+export declare function mockSensor(init: Init<SensorEntity> & {
+    value: string;
+}): EntityInput;
+export declare function mockSwitch(init?: Init<SwitchEntity>): EntityInput;
+export declare function mockAction(init?: Init<ActionEntity>): EntityInput;
+export declare function mockPerson(init?: Init<PersonEntity>): EntityInput;
+export declare function mockWeather(init?: Init<WeatherEntity>): EntityInput;
+export declare function mockGeneric(init: Init<GenericEntity> & {
+    value: string;
+}): EntityInput;
+export interface MockCall {
+    entityId: string;
+    command: string;
+    args?: Record<string, unknown>;
+}
+/** A fake media library: the items inside each folder, by folder id (`root` for the top level). */
+export type MockLibrary = Record<string, {
+    title?: string;
+    items: BrowseItem[];
+}>;
+/** A small library with the shapes a real one has: shelves, each holding playlists, albums,
+ * artists or stations, which in turn hold tracks. */
+export declare function mockLibrary(): MockLibrary;
+export interface MockIntegrationOptions {
+    id?: string;
+    /** What `browse` lists and `playMedia` plays. Defaults to none: the players have no library. */
+    library?: MockLibrary;
+    /** Entities by local id, built with the `mock*` builders. */
+    entities?: Record<string, EntityInput>;
+}
+/** In-memory integration with fixture entities, for tests, the gallery and screenshots. */
+export declare class MockIntegration extends BaseIntegration {
+    #private;
+    readonly id: string;
+    readonly calls: MockCall[];
+    constructor(options?: MockIntegrationOptions);
+    connect(): Promise<void>;
+    disconnect(): void;
+    /** Adds an entity, or replaces one. */
+    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;
+    browse(entityId: string, query: BrowseQuery): Promise<BrowseResult>;
+    command(entityId: string, name: string, args?: Record<string, unknown>): Promise<void>;
+}
+export {};

package/dist/mock.js

@@ -0,0 +1,448 @@
+import { BaseIntegration } from './base-integration.js';
+import { UnknownEntityError } from './entity.js';
+import { isCommandOf, } from './model/index.js';
+export function mockMediaPlayer(init = {}) {
+    const { capabilities, ...rest } = init;
+    return {
+        kind: 'mediaPlayer',
+        name: 'Player',
+        availability: 'ready',
+        playback: 'idle',
+        muted: false,
+        ...rest,
+        capabilities: {
+            volume: rest.volume !== undefined,
+            mute: true,
+            next: true,
+            previous: true,
+            browse: false,
+            search: false,
+            seek: false,
+            shuffle: false,
+            transfer: false,
+            group: false,
+            ...capabilities,
+        },
+    };
+}
+export function mockLight(init = {}) {
+    const { capabilities, ...rest } = init;
+    return {
+        kind: 'light',
+        name: 'Light',
+        availability: 'ready',
+        on: false,
+        ...rest,
+        capabilities: {
+            brightness: rest.brightness !== undefined,
+            colorTemperature: false,
+            color: false,
+            ...capabilities,
+        },
+    };
+}
+export function mockClimate(init = {}) {
+    const { capabilities, ...rest } = init;
+    return {
+        kind: 'climate',
+        name: 'Climate',
+        availability: 'ready',
+        mode: 'off',
+        unit: '°C',
+        ...rest,
+        capabilities: {
+            modes: ['off', 'heat'],
+            presets: [],
+            targetTemperature: rest.targetTemperature !== undefined,
+            step: 0.5,
+            range: { min: 5, max: 35 },
+            ...capabilities,
+        },
+    };
+}
+export function mockSensor(init) {
+    const numeric = Number(init.value);
+    return {
+        kind: 'sensor',
+        name: 'Sensor',
+        availability: 'ready',
+        ...(init.value.trim() !== '' && Number.isFinite(numeric) ? { numeric } : {}),
+        ...init,
+    };
+}
+export function mockSwitch(init = {}) {
+    return { kind: 'switch', name: 'Switch', availability: 'ready', on: false, ...init };
+}
+export function mockAction(init = {}) {
+    return { kind: 'action', name: 'Action', availability: 'ready', ...init };
+}
+export function mockPerson(init = {}) {
+    const location = init.location ?? 'home';
+    return {
+        kind: 'person',
+        name: 'Person',
+        availability: 'ready',
+        home: location === 'home',
+        location,
+        ...init,
+    };
+}
+export function mockWeather(init = {}) {
+    return {
+        kind: 'weather',
+        name: 'Weather',
+        availability: 'ready',
+        condition: 'sunny',
+        temperature: 20,
+        unit: '°C',
+        ...init,
+    };
+}
+export function mockGeneric(init) {
+    return { kind: 'generic', name: 'Entity', availability: 'ready', ...init };
+}
+/** Cover art for the mock library: a stable picture per item, from a placeholder service. */
+const cover = (id) => `https://picsum.photos/seed/${id}/400`;
+const libraryTrack = (id, title, artist) => ({
+    id,
+    title,
+    subtitle: artist,
+    artworkUrl: cover(id),
+    kind: 'track',
+    playable: true,
+    expandable: false,
+});
+const libraryFolder = (id, title, kind, subtitle) => ({
+    id,
+    title,
+    ...(subtitle ? { subtitle } : {}),
+    ...(kind === 'folder' ? {} : { artworkUrl: cover(id) }),
+    kind,
+    playable: kind !== 'folder',
+    expandable: true,
+});
+/** A small library with the shapes a real one has: shelves, each holding playlists, albums,
+ * artists or stations, which in turn hold tracks. */
+export function mockLibrary() {
+    return {
+        root: {
+            items: [
+                libraryFolder('recent', 'Recently played', 'folder'),
+                libraryFolder('playlists', 'Playlists', 'folder'),
+                libraryFolder('albums', 'Albums', 'folder'),
+                libraryFolder('artists', 'Artists', 'folder'),
+                libraryFolder('radio', 'Radio', 'folder'),
+            ],
+        },
+        recent: {
+            title: 'Recently played',
+            items: [
+                libraryTrack('t-blank-space', 'Blank Space', 'Taylor Swift'),
+                libraryTrack('t-dreams', 'Dreams', 'Fleetwood Mac'),
+                libraryTrack('t-kids', 'Kids', 'MGMT'),
+                libraryTrack('t-style', 'Style', 'Taylor Swift'),
+                libraryTrack('t-electric', 'Electric Feel', 'MGMT'),
+                libraryTrack('t-go-your-own-way', 'Go Your Own Way', 'Fleetwood Mac'),
+                libraryTrack('t-borderline', 'Borderline', 'Tame Impala'),
+            ],
+        },
+        playlists: {
+            title: 'Playlists',
+            items: [
+                libraryFolder('pl-morning', 'Morning coffee', 'playlist', '24 tracks'),
+                libraryFolder('pl-dinner', 'Dinner party', 'playlist', '41 tracks'),
+                libraryFolder('pl-focus', 'Deep focus', 'playlist', '60 tracks'),
+            ],
+        },
+        albums: {
+            title: 'Albums',
+            items: [
+                libraryFolder('al-1989', '1989', 'album', 'Taylor Swift'),
+                libraryFolder('al-rumours', 'Rumours', 'album', 'Fleetwood Mac'),
+                libraryFolder('al-oracular', 'Oracular Spectacular', 'album', 'MGMT'),
+                libraryFolder('al-currents', 'Currents', 'album', 'Tame Impala'),
+                libraryFolder('al-ram', 'Random Access Memories', 'album', 'Daft Punk'),
+                libraryFolder('al-folklore', 'Folklore', 'album', 'Taylor Swift'),
+                libraryFolder('al-hounds', 'Hounds of Love', 'album', 'Kate Bush'),
+            ],
+        },
+        artists: {
+            title: 'Artists',
+            items: [
+                libraryFolder('ar-swift', 'Taylor Swift', 'artist'),
+                libraryFolder('ar-mac', 'Fleetwood Mac', 'artist'),
+                libraryFolder('ar-mgmt', 'MGMT', 'artist'),
+            ],
+        },
+        radio: {
+            title: 'Radio',
+            items: [
+                { ...libraryFolder('rd-jazz', 'Jazz FM', 'radio'), expandable: false },
+                { ...libraryFolder('rd-lofi', 'Lofi Beats', 'radio'), expandable: false },
+            ],
+        },
+        'pl-morning': {
+            title: 'Morning coffee',
+            items: [
+                libraryTrack('t-dreams', 'Dreams', 'Fleetwood Mac'),
+                libraryTrack('t-kids', 'Kids', 'MGMT'),
+                libraryTrack('t-blank-space', 'Blank Space', 'Taylor Swift'),
+            ],
+        },
+        'al-1989': {
+            title: '1989',
+            items: [
+                libraryTrack('t-blank-space', 'Blank Space', 'Taylor Swift'),
+                libraryTrack('t-style', 'Style', 'Taylor Swift'),
+            ],
+        },
+        'al-rumours': {
+            title: 'Rumours',
+            items: [
+                libraryTrack('t-dreams', 'Dreams', 'Fleetwood Mac'),
+                libraryTrack('t-go-your-own-way', 'Go Your Own Way', 'Fleetwood Mac'),
+            ],
+        },
+        'al-oracular': {
+            title: 'Oracular Spectacular',
+            items: [
+                libraryTrack('t-kids', 'Kids', 'MGMT'),
+                libraryTrack('t-electric', 'Electric Feel', 'MGMT'),
+            ],
+        },
+        'al-currents': {
+            title: 'Currents',
+            items: [
+                libraryTrack('t-borderline', 'Borderline', 'Tame Impala'),
+                libraryTrack('t-let-it-happen', 'Let It Happen', 'Tame Impala'),
+            ],
+        },
+        'al-ram': {
+            title: 'Random Access Memories',
+            items: [
+                libraryTrack('t-get-lucky', 'Get Lucky', 'Daft Punk'),
+                libraryTrack('t-instant-crush', 'Instant Crush', 'Daft Punk'),
+            ],
+        },
+        'al-folklore': {
+            title: 'Folklore',
+            items: [
+                libraryTrack('t-cardigan', 'Cardigan', 'Taylor Swift'),
+                libraryTrack('t-august', 'August', 'Taylor Swift'),
+            ],
+        },
+        'al-hounds': {
+            title: 'Hounds of Love',
+            items: [
+                libraryTrack('t-running', 'Running Up That Hill', 'Kate Bush'),
+                libraryTrack('t-cloudbusting', 'Cloudbusting', 'Kate Bush'),
+            ],
+        },
+        'ar-swift': {
+            title: 'Taylor Swift',
+            items: [libraryFolder('al-1989', '1989', 'album')],
+        },
+        'ar-mac': { title: 'Fleetwood Mac', items: [libraryFolder('al-rumours', 'Rumours', 'album')] },
+        'ar-mgmt': {
+            title: 'MGMT',
+            items: [libraryFolder('al-oracular', 'Oracular Spectacular', 'album')],
+        },
+    };
+}
+const clamp01 = (value) => Math.min(1, Math.max(0, value));
+/** What a command does to an entity's state, for the kinds that have commands. */
+function applyCommand(entity, name, args = {}) {
+    const num = (key) => {
+        const value = args[key];
+        if (typeof value !== 'number' || !Number.isFinite(value)) {
+            throw new Error(`"${name}" needs a numeric "${key}"`);
+        }
+        return value;
+    };
+    switch (entity.kind) {
+        case 'mediaPlayer':
+            switch (name) {
+                case 'play':
+                    return { playback: 'playing' };
+                case 'pause':
+                    return { playback: 'paused' };
+                case 'togglePlay':
+                    return { playback: entity.playback === 'playing' ? 'paused' : 'playing' };
+                case 'setVolume':
+                    return { volume: clamp01(num('volume')) };
+                case 'setMuted':
+                    return { muted: args.muted === true };
+                case 'setShuffle':
+                    return { shuffle: args.shuffle === true };
+                case 'seek':
+                    return {
+                        position: Math.max(0, num('position')),
+                        positionUpdatedAt: new Date().toISOString(),
+                    };
+                default:
+                    return {};
+            }
+        case 'light':
+            switch (name) {
+                case 'turnOn':
+                    return { on: true };
+                case 'turnOff':
+                    return { on: false };
+                case 'toggle':
+                    return { on: !entity.on };
+                case 'setBrightness': {
+                    const brightness = clamp01(num('brightness'));
+                    return brightness === 0 ? { on: false } : { on: true, brightness };
+                }
+                case 'setColorTemperature':
+                    return { on: true, color: { mode: 'temperature', kelvin: num('kelvin') } };
+                case 'setColor':
+                    return {
+                        on: true,
+                        color: { mode: 'color', hue: num('hue'), saturation: num('saturation') },
+                    };
+                default:
+                    return {};
+            }
+        case 'climate':
+            switch (name) {
+                case 'setMode':
+                    return { mode: args.mode };
+                case 'setTargetTemperature':
+                    return { targetTemperature: num('temperature') };
+                case 'setPreset':
+                    return { preset: String(args.preset) };
+                default:
+                    return {};
+            }
+        case 'switch':
+            switch (name) {
+                case 'turnOn':
+                    return { on: true };
+                case 'turnOff':
+                    return { on: false };
+                case 'toggle':
+                    return { on: !entity.on };
+                default:
+                    return {};
+            }
+        case 'action':
+            return { lastTriggered: new Date().toISOString() };
+        default:
+            return {};
+    }
+}
+/** In-memory integration with fixture entities, for tests, the gallery and screenshots. */
+export class MockIntegration extends BaseIntegration {
+    id;
+    calls = [];
+    /** The inputs currently stored, so `update` can patch them. */
+    #inputs = new Map();
+    #library;
+    constructor(options = {}) {
+        super();
+        this.id = options.id ?? 'ha';
+        this.#library = options.library ?? {};
+        for (const [entityId, input] of Object.entries(options.entities ?? {})) {
+            this.#inputs.set(entityId, input);
+            this.setEntity(entityId, input);
+        }
+    }
+    connect() {
+        this.setStatus('connected');
+        return Promise.resolve();
+    }
+    disconnect() {
+        this.setStatus('disconnected');
+    }
+    /** Adds an entity, or replaces one. */
+    set(entityId, input) {
+        this.#inputs.set(entityId, input);
+        this.setEntity(entityId, input);
+    }
+    /** Patches an entity: top-level fields are replaced, `capabilities` and `media` are merged. */
+    update(entityId, patch) {
+        const current = this.#inputs.get(entityId);
+        if (!current) {
+            throw new UnknownEntityError(this.id, entityId);
+        }
+        const now = new Date().toISOString();
+        const merged = { ...current, ...patch, lastUpdated: now, lastChanged: now };
+        for (const key of ['capabilities', 'media']) {
+            const before = current[key];
+            const change = patch[key];
+            if (typeof before === 'object' && typeof change === 'object' && before && change) {
+                merged[key] = { ...before, ...change };
+            }
+        }
+        this.set(entityId, merged);
+    }
+    browse(entityId, query) {
+        if (!this.getEntity(entityId)) {
+            return Promise.reject(new UnknownEntityError(this.id, entityId));
+        }
+        if (query.search !== undefined) {
+            const needle = query.search.trim().toLowerCase();
+            const seen = new Set();
+            const items = Object.values(this.#library)
+                .flatMap((folder) => folder.items)
+                .filter((item) => {
+                const hit = needle !== '' &&
+                    `${item.title} ${item.subtitle ?? ''}`.toLowerCase().includes(needle) &&
+                    !seen.has(item.id);
+                seen.add(item.id);
+                return hit;
+            });
+            return Promise.resolve({ title: `Results for “${query.search}”`, items });
+        }
+        const folder = this.#library[query.path ?? 'root'];
+        return folder
+            ? Promise.resolve({ ...(folder.title ? { title: folder.title } : {}), items: folder.items })
+            : Promise.reject(new Error(`Nothing at "${query.path}"`));
+    }
+    #playMedia(entityId, item) {
+        const found = Object.values(this.#library)
+            .flatMap((folder) => folder.items)
+            .find((candidate) => candidate.id === item);
+        const current = this.#inputs.get(entityId);
+        if (!found?.playable || !current || current.kind !== 'mediaPlayer') {
+            return Promise.reject(new Error(`Cannot play "${String(item)}"`));
+        }
+        const now = new Date().toISOString();
+        this.set(entityId, {
+            ...current,
+            playback: 'playing',
+            media: {
+                title: found.title,
+                ...(found.subtitle ? { artist: found.subtitle } : {}),
+                ...(found.artworkUrl ? { artworkUrl: found.artworkUrl } : {}),
+            },
+            position: 0,
+            duration: 215,
+            positionUpdatedAt: now,
+            lastUpdated: now,
+            lastChanged: now,
+        });
+        return Promise.resolve();
+    }
+    command(entityId, name, args) {
+        this.calls.push({ entityId, command: name, ...(args ? { args } : {}) });
+        const entity = this.getEntity(entityId);
+        if (!entity) {
+            return Promise.reject(new UnknownEntityError(this.id, entityId));
+        }
+        if (!isCommandOf(entity.kind, name)) {
+            return Promise.reject(new Error(`A ${entity.kind} has no "${name}" command`));
+        }
+        if (entity.kind === 'mediaPlayer' && name === 'playMedia') {
+            return this.#playMedia(entityId, args?.item);
+        }
+        try {
+            this.update(entityId, applyCommand(entity, name, args));
+        }
+        catch (error) {
+            return Promise.reject(error instanceof Error ? error : new Error(String(error)));
+        }
+        return Promise.resolve();
+    }
+}