@hashsome/core 0.1.0

package/dist/client.js

@@ -0,0 +1,199 @@
+import { encodeMessage, parseServerMessage } from './protocol.js';
+/**
+ * Browser-side (and React-free) client for the runtime proxy. Ref-counts
+ * subscriptions, resubscribes and reconnects with backoff. Listeners receive
+ * `undefined` until the server has answered, then an entity or `null` (unknown entity).
+ */
+export class RemoteClient {
+    #options;
+    #socket;
+    #link = 'closed';
+    #linkListeners = new Set();
+    #integrationStatus = new Map();
+    #statusSnapshot = {};
+    #statusListeners = new Set();
+    #entities = new Map();
+    #listeners = new Map();
+    #pending = new Map();
+    #nextId = 1;
+    #retry = 0;
+    #timer;
+    #stopped = true;
+    constructor(options) {
+        this.#options = options;
+    }
+    get link() {
+        return this.#link;
+    }
+    connect() {
+        if (!this.#stopped) {
+            return;
+        }
+        this.#stopped = false;
+        this.#open();
+    }
+    close() {
+        this.#stopped = true;
+        clearTimeout(this.#timer);
+        this.#socket?.close();
+        this.#socket = undefined;
+        this.#setLink('closed');
+    }
+    onLinkChange(listener) {
+        this.#linkListeners.add(listener);
+        return () => this.#linkListeners.delete(listener) && undefined;
+    }
+    /** Status of a backend integration as reported by the runtime (`undefined` until known). */
+    getIntegrationStatus(integration) {
+        return this.#integrationStatus.get(integration);
+    }
+    getIntegrationStatuses() {
+        return this.#statusSnapshot;
+    }
+    onIntegrationStatusChange(listener) {
+        this.#statusListeners.add(listener);
+        return () => this.#statusListeners.delete(listener) && undefined;
+    }
+    getEntity(ref) {
+        return this.#entities.get(ref);
+    }
+    subscribe(ref, listener) {
+        let set = this.#listeners.get(ref);
+        if (!set) {
+            set = new Set();
+            this.#listeners.set(ref, set);
+            this.#send({ type: 'subscribe', ref });
+        }
+        set.add(listener);
+        listener(this.#entities.get(ref));
+        return () => {
+            set.delete(listener);
+            if (set.size === 0) {
+                this.#listeners.delete(ref);
+                this.#send({ type: 'unsubscribe', ref });
+            }
+        };
+    }
+    async command(ref, name, args) {
+        await this.#request((id) => ({
+            type: 'command',
+            id,
+            ref,
+            command: name,
+            ...(args ? { args } : {}),
+        }));
+    }
+    async browse(ref, query) {
+        return (await this.#request((id) => ({
+            type: 'query',
+            id,
+            ref,
+            query: 'browse',
+            args: { ...query },
+        })));
+    }
+    async history(ref, query) {
+        return (await this.#request((id) => ({
+            type: 'query',
+            id,
+            ref,
+            query: 'history',
+            args: { ...query },
+        })));
+    }
+    callRaw(integration, request) {
+        return this.#request((id) => ({ type: 'raw', id, integration, request }));
+    }
+    #request(build) {
+        const id = this.#nextId++;
+        return new Promise((resolve, reject) => {
+            if (this.#socket?.readyState !== 1) {
+                reject(new Error('Not connected to runtime'));
+                return;
+            }
+            this.#pending.set(id, { resolve, reject });
+            this.#send(build(id));
+        });
+    }
+    #setLink(status) {
+        if (status === this.#link) {
+            return;
+        }
+        this.#link = status;
+        for (const listener of Array.from(this.#linkListeners)) {
+            listener(status);
+        }
+    }
+    #send(message) {
+        if (this.#socket?.readyState === 1) {
+            this.#socket.send(encodeMessage(message));
+        }
+    }
+    #open() {
+        this.#setLink('connecting');
+        const socket = (this.#options.createSocket ?? ((url) => new WebSocket(url)))(this.#options.url);
+        this.#socket = socket;
+        socket.addEventListener('open', () => {
+            this.#retry = 0;
+            this.#setLink('open');
+            for (const ref of this.#listeners.keys()) {
+                this.#send({ type: 'subscribe', ref });
+            }
+        });
+        socket.addEventListener('message', (event) => {
+            const message = parseServerMessage(String(event.data));
+            if (message) {
+                this.#handle(message);
+            }
+        });
+        socket.addEventListener('close', () => {
+            if (this.#socket !== socket) {
+                return;
+            }
+            this.#socket = undefined;
+            for (const { reject } of this.#pending.values()) {
+                reject(new Error('Connection lost'));
+            }
+            this.#pending.clear();
+            this.#setLink('closed');
+            if (this.#stopped) {
+                return;
+            }
+            const min = this.#options.reconnectMinMs ?? 500;
+            const max = this.#options.reconnectMaxMs ?? 10_000;
+            const delay = Math.min(max, min * 2 ** this.#retry++);
+            this.#timer = setTimeout(() => this.#open(), delay);
+        });
+    }
+    #handle(message) {
+        switch (message.type) {
+            case 'entity':
+                this.#entities.set(message.ref, message.entity);
+                for (const listener of Array.from(this.#listeners.get(message.ref) ?? [])) {
+                    listener(message.entity);
+                }
+                break;
+            case 'status':
+                this.#integrationStatus.set(message.integration, message.status);
+                this.#statusSnapshot = Object.fromEntries(this.#integrationStatus);
+                for (const listener of Array.from(this.#statusListeners)) {
+                    listener();
+                }
+                break;
+            case 'result': {
+                const pending = this.#pending.get(message.id);
+                if (!pending) {
+                    break;
+                }
+                this.#pending.delete(message.id);
+                if (message.ok) {
+                    pending.resolve(message.data);
+                }
+                else {
+                    pending.reject(new Error(message.error));
+                }
+                break;
+            }
+        }
+    }
+}

package/dist/client.js.map

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

package/dist/codegen.d.ts

@@ -0,0 +1,6 @@
+import type { EntityRef } from './entity.ts';
+/**
+ * Generate an `entities.d.ts` that augments `KnownEntities`, so entity refs
+ * autocomplete and typos fail typechecking.
+ */
+export declare function generateEntityTypes(refs: readonly (EntityRef | string)[]): string;

package/dist/codegen.js

@@ -0,0 +1,19 @@
+/**
+ * Generate an `entities.d.ts` that augments `KnownEntities`, so entity refs
+ * autocomplete and typos fail typechecking.
+ */
+export function generateEntityTypes(refs) {
+    const unique = [...new Set(refs)].toSorted();
+    const lines = unique.map((ref) => `    ${JSON.stringify(ref)}: true;`);
+    return [
+        '// Generated by @hashsome/core. Do not edit.',
+        "import '@hashsome/core';",
+        '',
+        "declare module '@hashsome/core' {",
+        '  interface KnownEntities {',
+        ...lines,
+        '  }',
+        '}',
+        '',
+    ].join('\n');
+}

package/dist/codegen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.js","sourceRoot":"","sources":["../src/codegen.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAqC;IACvE,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACvE,OAAO;QACL,8CAA8C;QAC9C,0BAA0B;QAC1B,EAAE;QACF,mCAAmC;QACnC,6BAA6B;QAC7B,GAAG,KAAK;QACR,KAAK;QACL,GAAG;QACH,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/conformance.d.ts

@@ -0,0 +1,23 @@
+import type { Integration } from './integration.ts';
+import { type EntityKind } from './model/index.ts';
+export interface ConformanceOptions {
+    /** Shown in test names, e.g. `Home Assistant`. */
+    name: string;
+    /** The id the integration uses unless told otherwise (`ha`, `ma`). */
+    defaultId: string;
+    /** Builds the integration's mock, with the integration's own representative devices. */
+    createMock: (options?: {
+        id?: string;
+    }) => Integration;
+    /** Every kind the real integration can produce; the mock has to cover all of them. */
+    kinds: readonly EntityKind[];
+}
+/**
+ * The checks every integration's mock must pass, so a project can try any device without a
+ * backend. Run it from the integration package's own tests:
+ *
+ *     runIntegrationConformance({ name, defaultId, kinds, createMock });
+ *
+ * Imports `vitest`, which is why it lives behind its own `@hashsome/core/conformance` entry point.
+ */
+export declare function runIntegrationConformance(options: ConformanceOptions): void;

package/dist/conformance.js

@@ -0,0 +1,196 @@
+import { describe, expect, test } from 'vitest';
+import { UnknownEntityError } from './entity.js';
+import { COMMAND_NAMES } from './model/index.js';
+const AVAILABILITY = ['ready', 'unavailable', 'unknown'];
+/**
+ * The checks every integration's mock must pass, so a project can try any device without a
+ * backend. Run it from the integration package's own tests:
+ *
+ *     runIntegrationConformance({ name, defaultId, kinds, createMock });
+ *
+ * Imports `vitest`, which is why it lives behind its own `@hashsome/core/conformance` entry point.
+ */
+export function runIntegrationConformance(options) {
+    const { name, defaultId, createMock, kinds } = options;
+    describe(`${name} mock conformance`, () => {
+        test('uses the integration’s default id, and accepts another one', () => {
+            expect(createMock().id).toBe(defaultId);
+            expect(createMock({ id: 'other' }).id).toBe('other');
+        });
+        test('connects, and then lists a representative set of entities', async () => {
+            const mock = createMock();
+            await mock.connect();
+            expect(mock.status).toBe('connected');
+            expect(mock.listEntities().length).toBeGreaterThan(0);
+        });
+        test('covers every kind the integration can produce', async () => {
+            const mock = createMock();
+            await mock.connect();
+            const present = new Set(mock.listEntities().map((entity) => entity.kind));
+            expect(kinds.filter((kind) => !present.has(kind))).toEqual([]);
+        });
+        test('every entity is valid for its kind, and addressed by this integration', async () => {
+            const mock = createMock();
+            await mock.connect();
+            const problems = [];
+            for (const entity of mock.listEntities()) {
+                if (!entity.ref.startsWith(`${mock.id}:`)) {
+                    problems.push(`${entity.ref}: not addressed by "${mock.id}"`);
+                }
+                if (!Object.keys(COMMAND_NAMES).includes(entity.kind)) {
+                    problems.push(`${entity.ref}: unknown kind "${entity.kind}"`);
+                }
+                if (entity.name.length === 0) {
+                    problems.push(`${entity.ref}: empty name`);
+                }
+                if (!AVAILABILITY.includes(entity.availability)) {
+                    problems.push(`${entity.ref}: bad availability "${entity.availability}"`);
+                }
+                if (mock.getEntity(localId(mock.id, entity)) !== entity) {
+                    problems.push(`${entity.ref}: getEntity does not return the listed entity`);
+                }
+            }
+            expect(problems).toEqual([]);
+        });
+        test('includes an unavailable device, so a dashboard can show that state', async () => {
+            const mock = createMock();
+            await mock.connect();
+            expect(mock.listEntities().some((entity) => entity.availability === 'unavailable')).toBe(true);
+        });
+        test('subscribe delivers the current entity at once, and throws for an unknown id', async () => {
+            const mock = createMock();
+            await mock.connect();
+            const [first] = mock.listEntities();
+            expect(first).toBeDefined();
+            const seen = [];
+            mock.subscribe(localId(mock.id, first), (entity) => seen.push(entity))();
+            expect(seen).toEqual([first]);
+            let thrown;
+            try {
+                mock.subscribe('does-not-exist', () => { });
+            }
+            catch (error) {
+                thrown = error;
+            }
+            expect(thrown).toBeInstanceOf(UnknownEntityError);
+        });
+        test('commands reject for an unknown entity and for a command the kind does not define', async () => {
+            const mock = createMock();
+            await mock.connect();
+            await expect(mock.command('does-not-exist', 'toggle')).rejects.toThrow(/does-not-exist/);
+            const [first] = mock.listEntities();
+            await expect(mock.command(localId(mock.id, first), 'definitely-not-a-command')).rejects.toThrow(/definitely-not-a-command/);
+        });
+        test('every command of a kind with commands runs on an entity of that kind', async () => {
+            const mock = createMock();
+            await mock.connect();
+            const failures = [];
+            for (const entity of mock.listEntities()) {
+                if (entity.availability !== 'ready') {
+                    continue;
+                }
+                const argsFor = SAMPLE_ARGS[entity.kind] ?? {};
+                for (const command of COMMAND_NAMES[entity.kind]) {
+                    if (command === 'playMedia') {
+                        continue; // needs a real item id; the library test above plays one
+                    }
+                    try {
+                        await mock.command(localId(mock.id, entity), command, argsFor[command]);
+                    }
+                    catch (error) {
+                        failures.push(`${entity.ref} ${command}: ${String(error)}`);
+                    }
+                }
+            }
+            expect(failures).toEqual([]);
+        });
+        test('a player that reports a library can be browsed, searched and played from', async () => {
+            const mock = createMock();
+            await mock.connect();
+            const failures = [];
+            for (const entity of mock.listEntities()) {
+                if (entity.kind !== 'mediaPlayer' || !entity.capabilities.browse) {
+                    continue;
+                }
+                const id = localId(mock.id, entity);
+                if (!mock.browse) {
+                    failures.push(`${entity.ref}: reports browse but the integration has no browse()`);
+                    continue;
+                }
+                const root = await mock.browse(id, {});
+                if (root.items.length === 0) {
+                    failures.push(`${entity.ref}: the top level of the library is empty`);
+                }
+                for (const item of root.items) {
+                    if (item.title === '' || item.id === '') {
+                        failures.push(`${entity.ref}: an item has no id or title`);
+                    }
+                }
+                const folder = root.items.find((item) => item.expandable);
+                if (folder) {
+                    const inside = await mock.browse(id, { path: folder.id });
+                    if (inside.items.length === 0) {
+                        failures.push(`${entity.ref}: "${folder.title}" lists nothing`);
+                    }
+                }
+                const playable = await firstPlayable(mock, id);
+                if (!playable) {
+                    failures.push(`${entity.ref}: nothing in the library can be played`);
+                }
+                else {
+                    try {
+                        await mock.command(id, 'playMedia', { item: playable });
+                    }
+                    catch (error) {
+                        failures.push(`${entity.ref} playMedia: ${String(error)}`);
+                    }
+                }
+                if (entity.capabilities.search) {
+                    const found = await mock.browse(id, { search: root.items[0]?.title.slice(0, 3) ?? 'a' });
+                    if (!Array.isArray(found.items)) {
+                        failures.push(`${entity.ref}: search did not return a list`);
+                    }
+                }
+            }
+            expect(failures).toEqual([]);
+        });
+        test('the mock never carries credentials', async () => {
+            const mock = createMock();
+            await mock.connect();
+            expect(JSON.stringify(mock.listEntities())).not.toMatch(/token|password|secret/i);
+        });
+    });
+}
+const localId = (integrationId, entity) => entity.ref.slice(integrationId.length + 1);
+/** Arguments that make each command valid, for the commands that take any. */
+const SAMPLE_ARGS = {
+    mediaPlayer: { setVolume: { volume: 0.5 }, setMuted: { muted: true }, seek: { position: 30 } },
+    light: {
+        setBrightness: { brightness: 0.5 },
+        setColorTemperature: { kelvin: 3000 },
+        setColor: { hue: 120, saturation: 80 },
+    },
+    climate: {
+        setMode: { mode: 'off' },
+        setTargetTemperature: { temperature: 20 },
+        setPreset: { preset: 'home' },
+    },
+};
+/** The id of the first playable item found by walking the library, a few levels down. */
+async function firstPlayable(integration, entityId, path, depth = 0) {
+    if (!integration.browse || depth > 3) {
+        return undefined;
+    }
+    const level = await integration.browse(entityId, path === undefined ? {} : { path });
+    const direct = level.items.find((item) => item.playable && !item.expandable);
+    if (direct) {
+        return direct.id;
+    }
+    for (const item of level.items.filter((candidate) => candidate.expandable)) {
+        const found = await firstPlayable(integration, entityId, item.id, depth + 1);
+        if (found) {
+            return found;
+        }
+    }
+    return undefined;
+}

package/dist/conformance.js.map

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

package/dist/emitter.d.ts

@@ -0,0 +1,8 @@
+import type { Unsubscribe } from './integration.ts';
+/** Tiny listener set shared by integrations. */
+export declare class Emitter<T> {
+    #private;
+    on(listener: (value: T) => void): Unsubscribe;
+    emit(value: T): void;
+    get size(): number;
+}

package/dist/emitter.js

@@ -0,0 +1,18 @@
+/** Tiny listener set shared by integrations. */
+export class Emitter {
+    #listeners = new Set();
+    on(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    emit(value) {
+        for (const listener of Array.from(this.#listeners)) {
+            listener(value);
+        }
+    }
+    get size() {
+        return this.#listeners.size;
+    }
+}

package/dist/emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.js","sourceRoot":"","sources":["../src/emitter.ts"],"names":[],"mappings":"AAEA,gDAAgD;AAChD,MAAM,OAAO,OAAO;IAClB,UAAU,GAAG,IAAI,GAAG,EAAsB,CAAC;IAE3C,EAAE,CAAC,QAA4B;QAC7B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACnC,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,KAAQ;QACX,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YACnD,QAAQ,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;IAC9B,CAAC;CACF"}

package/dist/entity.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Entity refs address an entity across integrations: `<integration>:<id>`,
+ * e.g. `ha:light.kitchen_lamp` or `ma:living_room`.
+ *
+ * `KnownEntities` is empty by default. Generated `entities.d.ts` files (see
+ * `generateEntityTypes`) augment it so refs autocomplete and are type-checked.
+ *
+ * The entity itself — the generic model every integration produces — lives in `./model/`.
+ */
+export interface KnownEntities {
+}
+export type EntityRef = keyof KnownEntities extends never ? `${string}:${string}` : Extract<keyof KnownEntities, string>;
+export interface ParsedEntityRef {
+    integration: string;
+    id: string;
+}
+export declare function parseEntityRef(ref: string): ParsedEntityRef;
+export declare function formatEntityRef(integration: string, id: string): EntityRef;
+/** Thrown by `Integration.subscribe` (and `command`) for an id the integration does not have. */
+export declare class UnknownEntityError extends Error {
+    readonly integration: string;
+    readonly entityId: string;
+    constructor(integration: string, entityId: string);
+}

package/dist/entity.js

@@ -0,0 +1,21 @@
+export function parseEntityRef(ref) {
+    const index = ref.indexOf(':');
+    if (index <= 0 || index === ref.length - 1) {
+        throw new Error(`Invalid entity ref "${ref}", expected "<integration>:<id>"`);
+    }
+    return { integration: ref.slice(0, index), id: ref.slice(index + 1) };
+}
+export function formatEntityRef(integration, id) {
+    return `${integration}:${id}`;
+}
+/** Thrown by `Integration.subscribe` (and `command`) for an id the integration does not have. */
+export class UnknownEntityError extends Error {
+    integration;
+    entityId;
+    constructor(integration, entityId) {
+        super(`Unknown entity "${integration}:${entityId}"`);
+        this.integration = integration;
+        this.entityId = entityId;
+        this.name = 'UnknownEntityError';
+    }
+}

package/dist/entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.js","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"AAqBA,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,KAAK,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,uBAAuB,GAAG,kCAAkC,CAAC,CAAC;IAChF,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,WAAmB,EAAE,EAAU;IAC7D,OAAO,GAAG,WAAW,IAAI,EAAE,EAAe,CAAC;AAC7C,CAAC;AAED,iGAAiG;AACjG,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,WAAW,CAAS;IACpB,QAAQ,CAAS;IAE1B,YAAY,WAAmB,EAAE,QAAgB;QAC/C,KAAK,CAAC,mBAAmB,WAAW,IAAI,QAAQ,GAAG,CAAC,CAAC;QACrD,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './entity.ts';
+export * from './model/index.ts';
+export * from './integration.ts';
+export * from './base-integration.ts';
+export * from './mock.ts';
+export * from './protocol.ts';
+export * from './codegen.ts';
+export * from './client.ts';
+export * from './local-client.ts';

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from './entity.js';
+export * from './model/index.js';
+export * from './integration.js';
+export * from './base-integration.js';
+export * from './mock.js';
+export * from './protocol.js';
+export * from './codegen.js';
+export * from './client.js';
+export * from './local-client.js';

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC"}

package/dist/integration.d.ts

@@ -0,0 +1,61 @@
+import type { EntityRef } from './entity.ts';
+import type { BrowseQuery, BrowseResult, Entity, HistoryQuery, HistoryResult } from './model/index.ts';
+export type ConnectionStatus = 'connecting' | 'connected' | 'disconnected' | 'error';
+export type Unsubscribe = () => void;
+/**
+ * A backend the runtime can talk to (Home Assistant, Music Assistant, ...). This is the whole
+ * surface a third-party integration package implements — see ARCHITECTURE.md, "The integration
+ * contract", for the rules each member must follow.
+ *
+ * Integrations work only in **local ids** (the part of a ref after `<integration>:`); the runtime
+ * does all the addressing, and `BaseIntegration` stamps `ref` onto the entities it stores.
+ */
+export interface Integration {
+    /** The prefix of every ref this integration owns. Fixed for the instance's lifetime. */
+    readonly id: string;
+    readonly status: ConnectionStatus;
+    /** Resolves once connected **and** the first full set of entities is loaded; rejects if the
+     * first attempt fails; idempotent. After a first success the integration reconnects itself. */
+    connect(): Promise<void>;
+    /** Synchronous and idempotent: closes the link, cancels timers, rejects in-flight commands. */
+    disconnect(): void;
+    /** Called only when the status actually changes. */
+    onStatusChange(listener: (status: ConnectionStatus) => void): Unsubscribe;
+    listEntities(): Entity[];
+    getEntity(entityId: string): Entity | undefined;
+    /**
+     * Calls `listener` immediately with the current entity, then on every change (`undefined` if
+     * the entity is removed). Throws `UnknownEntityError` for an id this integration does not have.
+     */
+    subscribe(entityId: string, listener: (entity: Entity | undefined) => void): Unsubscribe;
+    /**
+     * Runs a named command from the entity's kind (`setVolume`, `next`). Resolves once the backend
+     * has accepted it, not when the state changes. Rejects with a displayable `Error` for an
+     * unknown entity, a command the kind does not define, invalid arguments, or a refusing backend.
+     * Arguments come from a browser: validate them.
+     */
+    command(entityId: string, name: string, args?: Record<string, unknown>): Promise<void>;
+    /**
+     * Lists one level of the entity's media library (or searches it). Only for players that report
+     * `capabilities.browse`; the library is the integration's own, with no mixing across backends.
+     * Rejects with a displayable `Error` for an unknown entity or path. Arguments come from a browser.
+     */
+    browse?(entityId: string, query: BrowseQuery): Promise<BrowseResult>;
+    /**
+     * The entity's past values, from the backend's own record (Home Assistant's long-term
+     * statistics), bucketed. Optional: only for backends that keep history. Resolves with no points
+     * for an entity with none, and rejects with a displayable `Error` for an unknown entity.
+     * Arguments come from a browser: validate them.
+     */
+    history?(entityId: string, query: HistoryQuery): Promise<HistoryResult>;
+    /**
+     * 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
+     * refuse anything else. The runtime serves only image responses. Optional: omit it when entities
+     * only carry addresses the browser can open itself.
+     */
+    fetchAsset?(path: string): Promise<Response>;
+    /** Escape hatch: a backend-specific request no command covers. `@hashsome/ui` never calls it. */
+    callRaw?(request: Record<string, unknown>): Promise<unknown>;
+}
+export type { EntityRef };

package/dist/integration.js

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