@glasshome/sync-layer 0.1.0

package/dist/commands/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Command types
+ *
+ * Type definitions for service calls and commands.
+ *
+ * @packageDocumentation
+ */
+import type { Domain, ServiceCall, ServiceName, WsCommandType } from "@glasshome/ha-types";
+import type { EntityId } from "../core/types";
+/**
+ * Service call options
+ */
+export interface ServiceCallOptions {
+    /** Entity ID or array of entity IDs to target */
+    entity_id?: EntityId | EntityId[];
+    /** Area ID or array of area IDs to target */
+    area_id?: string | string[];
+    /** Device ID or array of device IDs to target */
+    device_id?: string | string[];
+}
+/**
+ * Service call target
+ *
+ * Defines what entities the service call should affect
+ */
+export interface ServiceTarget {
+    /** Entity IDs */
+    entity_id?: string | string[];
+    /** Device IDs */
+    device_id?: string | string[];
+    /** Area IDs */
+    area_id?: string | string[];
+}
+/**
+ * Service call with full context
+ */
+export interface ServiceCallContext {
+    /** Domain (e.g., "light", "switch") */
+    domain: Domain;
+    /** Service name (e.g., "turn_on", "toggle") */
+    service: ServiceName<Domain>;
+    /** Service data */
+    serviceData?: ServiceCall<Domain, ServiceName<Domain>>;
+    /** Target entities/devices/areas */
+    target?: ServiceTarget;
+}
+/**
+ * Command success result
+ */
+export interface CommandSuccess<T = unknown> {
+    success: true;
+    result: T;
+}
+/**
+ * Command error result
+ */
+export interface CommandError {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Command result (success or error)
+ */
+export type CommandResult<T = unknown> = CommandSuccess<T> | CommandError;
+/**
+ * Entity registry update fields
+ *
+ * Fields that can be updated in the entity registry
+ */
+export interface EntityUpdateFields {
+    /** Friendly name */
+    name?: string;
+    /** Icon */
+    icon?: string;
+    /** Area ID */
+    area_id?: string | null;
+    /** Disabled by (null to enable) */
+    disabled_by?: string | null;
+    /** Hidden by (null to unhide) */
+    hidden_by?: string | null;
+}
+/**
+ * Entity registry update request
+ */
+export interface EntityUpdateRequest {
+    /** Entity ID to update */
+    entity_id: EntityId;
+    /** Fields to update */
+    updates: EntityUpdateFields;
+}
+/**
+ * Generic WebSocket command
+ */
+export interface GenericCommand {
+    /** Command type */
+    type: WsCommandType | string;
+    /** Command payload */
+    [key: string]: unknown;
+}
+/**
+ * Command execution options
+ */
+export interface CommandOptions {
+    /** Timeout in milliseconds */
+    timeout?: number;
+    /** Retry on failure */
+    retry?: boolean;
+    /** Number of retry attempts */
+    retries?: number;
+}

package/dist/connection/adapter.d.ts

@@ -0,0 +1,48 @@
+/**
+ * HA Connection Adapter
+ *
+ * Wraps home-assistant-js-websocket Connection to SyncLayerConnection interface.
+ * This allows seamless swapping between mock and real connections.
+ *
+ * Debug listeners intercept messages at the adapter boundary:
+ * - Outgoing: fired from sendMessagePromise, subscribeMessage, subscribeEvents
+ * - Incoming: fired from subscribeMessage/subscribeEvents callbacks and sendMessagePromise responses
+ *
+ * @packageDocumentation
+ */
+import type { Connection } from "home-assistant-js-websocket";
+import type { SyncLayerConnection } from "./types";
+/**
+ * Register a listener for all outgoing WebSocket messages.
+ * Returns an unsubscribe function.
+ *
+ * @param listener - Function called with each outgoing message object
+ * @returns Unsubscribe function to remove the listener
+ */
+export declare function addDebugOutgoingMessageListener(listener: (message: any) => void): () => void;
+/**
+ * Register a listener for all incoming WebSocket messages.
+ * Returns an unsubscribe function. Receives subscription updates,
+ * event callbacks, and sendMessagePromise responses.
+ *
+ * @param listener - Function called with each incoming message object
+ * @returns Unsubscribe function to remove the listener
+ */
+export declare function addDebugIncomingMessageListener(listener: (message: any) => void): () => void;
+/**
+ * Wrap HA Connection to SyncLayerConnection interface
+ *
+ * This adapter makes the real HA Connection compatible with our unified interface,
+ * allowing it to be used interchangeably with MockConnection.
+ *
+ * @param conn - Home Assistant WebSocket connection
+ * @returns Wrapped connection implementing SyncLayerConnection
+ *
+ * @example
+ * ```typescript
+ * const haConn = await createConnection({ auth });
+ * const wrappedConn = wrapHAConnection(haConn);
+ * await syncLayer.connect({ connection: wrappedConn });
+ * ```
+ */
+export declare function wrapHAConnection(conn: Connection): SyncLayerConnection;

package/dist/connection/auth.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Authentication Helpers
+ *
+ * Provides OAuth and token-based authentication for Home Assistant connections.
+ *
+ * @packageDocumentation
+ */
+import { type Auth } from "home-assistant-js-websocket";
+/**
+ * Options for OAuth authentication flow
+ */
+export interface OAuthOptions {
+    /**
+     * Home Assistant instance URL
+     * (e.g., "https://homeassistant.local:8123")
+     */
+    url: string;
+    /**
+     * Client ID for OAuth
+     * Typically the same as the Home Assistant URL
+     */
+    clientId: string;
+    /**
+     * Redirect URI after OAuth authorization
+     * (e.g., "https://myapp.com/auth/callback")
+     */
+    redirectUri?: string;
+    /**
+     * Optional authorization code if already obtained
+     * If provided, will be used directly instead of starting OAuth flow
+     */
+    authCode?: string;
+    /**
+     * Optional function to get authorization code
+     * If provided, will be called to get the code before token exchange
+     */
+    getAuthCode?: () => Promise<string>;
+    /**
+     * Optional function to save auth data
+     * Useful for persisting auth tokens
+     */
+    saveAuth?: (auth: Auth) => void | Promise<void>;
+    /**
+     * Optional function to load saved auth data
+     */
+    loadAuth?: () => Promise<Auth | null>;
+    /**
+     * Optional flag to limit to specific Home Assistant instance
+     */
+    limitHassInstance?: boolean;
+}
+/**
+ * Authenticate using OAuth flow
+ *
+ * This function uses `getAuth` from `home-assistant-js-websocket` which:
+ * 1. Opens Home Assistant authorization page in a popup
+ * 2. Waits for user authorization
+ * 3. Exchanges authorization code for tokens
+ * 4. Returns authenticated Auth object
+ *
+ * Note: For a complete OAuth flow, you typically need to:
+ * - Set up a redirect URI endpoint in your app
+ * - Handle the OAuth callback with the authorization code
+ * - Use `getAuthCode` callback to provide the code
+ *
+ * Alternatively, `getAuth` can automatically handle the flow in browser environments
+ * by opening a popup and listening for the callback.
+ *
+ * @param options - OAuth options
+ * @returns Authenticated Auth object
+ *
+ * @example
+ * ```typescript
+ * // Basic OAuth flow (browser only)
+ * const auth = await authenticateWithOAuth({
+ *   url: 'https://homeassistant.local:8123',
+ *   clientId: 'https://homeassistant.local:8123',
+ *   redirectUri: 'https://myapp.com/auth/callback',
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // OAuth with custom code handling
+ * const auth = await authenticateWithOAuth({
+ *   url: 'https://homeassistant.local:8123',
+ *   clientId: 'https://homeassistant.local:8123',
+ *   redirectUri: 'https://myapp.com/auth/callback',
+ *   getAuthCode: async () => {
+ *     // Wait for user to authorize and get code from callback
+ *     return await waitForAuthCode();
+ *   },
+ * });
+ * ```
+ */
+export declare function authenticateWithOAuth(options: OAuthOptions): Promise<Auth>;
+/**
+ * Authenticate using a long-lived token
+ *
+ * @param url - Home Assistant instance URL
+ * @param token - Long-lived access token
+ * @returns Authenticated Auth object
+ *
+ * @example
+ * ```typescript
+ * const auth = authenticateWithToken(
+ *   'https://homeassistant.local:8123',
+ *   'your_long_lived_token'
+ * );
+ * ```
+ */
+export declare function authenticateWithToken(url: string, token: string): Auth;
+/**
+ * Check if auth object is valid
+ *
+ * @param auth - Auth object to check
+ * @returns True if auth is valid
+ */
+export declare function isAuthValid(auth: Auth): Promise<boolean>;
+/**
+ * Refresh auth tokens
+ *
+ * @param auth - Auth object to refresh
+ * @returns Refreshed Auth object
+ */
+export declare function refreshAuth(auth: Auth): Promise<Auth>;

package/dist/connection/manager.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Connection Manager
+ *
+ * Handles WebSocket connection lifecycle, authentication,
+ * and initial data loading.
+ *
+ * @packageDocumentation
+ */
+import { type Auth, type Connection, type ConnectionOptions as HAConnectionOptions } from "home-assistant-js-websocket";
+import { type OAuthOptions } from "./auth";
+/**
+ * Options for initializing a connection
+ */
+export interface ConnectionOptions {
+    url: string;
+    auth: Auth | string | OAuthOptions;
+    createSocket?: HAConnectionOptions["createSocket"];
+    onConnect?: () => void;
+    onDisconnect?: () => void;
+    onReconnect?: () => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Initialize connection to Home Assistant
+ */
+export declare function initConnection(options: ConnectionOptions): Promise<Connection>;
+/**
+ * Disconnect from Home Assistant
+ */
+export declare function disconnect(): void;
+/**
+ * Get current connection
+ */
+export declare function getConnection(): Connection | null;
+/**
+ * Check if currently connected
+ */
+export declare function isConnected(): boolean;
+/**
+ * Refresh all data
+ */
+export declare function refreshData(): Promise<void>;

package/dist/connection/subscriptions.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Event Subscriptions
+ *
+ * Sets up WebSocket event subscriptions to keep state in sync
+ * with Home Assistant.
+ *
+ * @packageDocumentation
+ */
+import type { SyncLayerConnection } from "./types";
+/**
+ * Subscribe to all relevant events from Home Assistant
+ */
+export declare function subscribeToUpdates(conn: SyncLayerConnection): Promise<void>;
+/**
+ * Clean up all active subscriptions
+ */
+export declare function cleanupSubscriptions(): Promise<void>;
+/**
+ * Check if subscriptions are active
+ */
+export declare function hasActiveSubscriptions(): boolean;
+/**
+ * Get number of active subscriptions
+ */
+export declare function getSubscriptionCount(): number;

package/dist/connection/types.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Connection Interface Types
+ *
+ * Defines the unified interface for both mock and real Home Assistant connections.
+ * This allows seamless swapping between test and production connections.
+ *
+ * @packageDocumentation
+ */
+import type { HAEvent } from "@glasshome/ha-types";
+import type { Fixtures } from "../testing/types";
+/**
+ * Unified connection interface for Home Assistant connections
+ *
+ * This interface is implemented by both:
+ * - MockConnection (for testing)
+ * - Wrapped HA Connection (for production)
+ *
+ * @example
+ * ```typescript
+ * // In tests
+ * const mockConn: SyncLayerConnection = new MockConnection(fixtures);
+ * await syncLayer.connect({ connection: mockConn });
+ *
+ * // In production
+ * const haConn = await createConnection({ auth });
+ * const wrappedConn: SyncLayerConnection = wrapHAConnection(haConn);
+ * await syncLayer.connect({ connection: wrappedConn });
+ * ```
+ */
+export interface SyncLayerConnection {
+    /**
+     * Connect to Home Assistant (or mock)
+     *
+     * Establishes the WebSocket connection. For real HA connections,
+     * this is called automatically by createConnection. For mock connections,
+     * this simulates the connection process.
+     *
+     * @returns Promise that resolves when connection is established
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from Home Assistant
+     *
+     * Closes the WebSocket connection and cleans up resources.
+     */
+    disconnect(): void;
+    /**
+     * Check if connection is currently active
+     *
+     * @returns true if connected, false otherwise
+     */
+    get connected$(): boolean;
+    /**
+     * Authenticate with Home Assistant
+     *
+     * Sends authentication credentials. For real HA connections,
+     * authentication is handled during connection creation. For mock connections,
+     * this simulates the authentication process.
+     *
+     * @param accessToken - Access token for authentication
+     * @returns Promise that resolves when authentication completes
+     */
+    authenticate(accessToken: string): Promise<void>;
+    /**
+     * Get current authentication state
+     *
+     * @returns Authentication state: "pending", "authenticated", or "failed"
+     */
+    get authState(): "pending" | "authenticated" | "failed";
+    /**
+     * Subscribe to Home Assistant events
+     *
+     * Registers a callback to receive events of a specific type (or all events).
+     *
+     * @param callback - Function called when events are received
+     * @param eventType - Optional event type filter (e.g., "entity_registry_updated")
+     * @returns Promise resolving to unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = await connection.subscribeEvents((event) => {
+     *   console.log("Event received:", event);
+     * }, "entity_registry_updated");
+     *
+     * // Later, unsubscribe
+     * await unsubscribe();
+     * ```
+     */
+    subscribeEvents(callback: (event: HAEvent<any>) => void, eventType?: string): Promise<() => void>;
+    /**
+     * Subscribe to message stream
+     *
+     * Used for streaming subscriptions like history/stream.
+     * Sends a subscription message and receives streaming responses.
+     *
+     * @param callback - Function called when messages are received
+     * @param message - Subscription message (e.g., { type: "history/stream", ... })
+     * @returns Promise resolving to unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = await connection.subscribeMessage((message) => {
+     *   console.log("Stream message:", message);
+     * }, {
+     *   type: "history/stream",
+     *   entity_ids: ["sensor.temperature"],
+     *   start_time: startTime.toISOString(),
+     * });
+     *
+     * // Later, unsubscribe
+     * await unsubscribe();
+     * ```
+     */
+    subscribeMessage<T>(callback: (message: T) => void, message: any): Promise<() => Promise<void>>;
+    /**
+     * Send a message and wait for response
+     *
+     * Sends a WebSocket message and returns a promise that resolves
+     * with the response.
+     *
+     * @param message - Message to send
+     * @returns Promise resolving to the response data
+     *
+     * @example
+     * ```typescript
+     * const states = await connection.sendMessagePromise({
+     *   type: "get_states",
+     * });
+     * ```
+     */
+    sendMessagePromise<T>(message: any): Promise<T>;
+    /**
+     * Add event listener for WebSocket messages
+     *
+     * Registers a handler for all WebSocket messages (not just events).
+     * Useful for listening to auth messages, connection status, etc.
+     *
+     * @param handler - Function called when any message is received
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = connection.addEventListener((message) => {
+     *   console.log("Any message:", message);
+     * });
+     *
+     * // Later, unsubscribe
+     * unsubscribe();
+     * ```
+     */
+    addEventListener(handler: (message: any) => void): () => void;
+    /**
+     * Get fixtures (MockConnection only)
+     *
+     * Returns the fixture data for mock connections. SyncLayer uses this
+     * to load fixtures into its store during connection setup.
+     *
+     * @returns Fixture data (entities, registries, etc.)
+     */
+    getFixtures?(): Fixtures;
+}

package/dist/core/reducers.d.ts

@@ -0,0 +1,99 @@
+/**
+ * State update reducers
+ *
+ * These functions handle state updates in response to events from
+ * Home Assistant. They use SolidJS store's produce() for safe mutations.
+ *
+ * NOTE: All index maintenance code has been stripped.
+ * Indices are derived reactively in Plan 03.
+ *
+ * @packageDocumentation
+ */
+import type { EntityRegistryEntry } from "@glasshome/ha-types";
+import type { AreaRegistryEntry, DeviceRegistryEntry, EntityId, FloorRegistryEntry, HassEntity, LabelRegistryEntry, StatisticData, StatisticMetadata } from "./types";
+/**
+ * Bulk update multiple entities
+ *
+ * Used during initial load or bulk sync operations.
+ *
+ * @param entities - Array of entity states
+ */
+export declare function bulkUpdateEntities(entities: HassEntity[]): void;
+/**
+ * Update entity registry entry
+ *
+ * @param entry - Entity registry entry
+ */
+export declare function updateEntityRegistry(entry: EntityRegistryEntry): void;
+/**
+ * Remove entity registry entry
+ *
+ * @param entityId - Entity ID to remove
+ */
+export declare function removeEntityRegistry(entityId: EntityId): void;
+/**
+ * Bulk update entity registry
+ *
+ * @param entries - Array of registry entries
+ */
+export declare function bulkUpdateEntityRegistry(entries: EntityRegistryEntry[]): void;
+/**
+ * Update device registry entry
+ *
+ * @param device - Device registry entry
+ */
+export declare function updateDevice(device: DeviceRegistryEntry): void;
+/**
+ * Remove device registry entry
+ *
+ * @param deviceId - Device ID to remove
+ */
+export declare function removeDevice(deviceId: string): void;
+/**
+ * Update area registry entry
+ *
+ * @param area - Area registry entry
+ */
+export declare function updateArea(area: AreaRegistryEntry): void;
+/**
+ * Remove area registry entry
+ *
+ * @param areaId - Area ID to remove
+ */
+export declare function removeArea(areaId: string): void;
+/**
+ * Update floor registry entry
+ *
+ * @param floor - Floor registry entry
+ */
+export declare function updateFloor(floor: FloorRegistryEntry): void;
+/**
+ * Remove floor registry entry
+ *
+ * @param floorId - Floor ID to remove
+ */
+export declare function removeFloor(floorId: string): void;
+/**
+ * Update label registry entry
+ *
+ * @param label - Label registry entry
+ */
+export declare function updateLabel(label: LabelRegistryEntry): void;
+/**
+ * Remove label registry entry
+ *
+ * @param labelId - Label ID to remove
+ */
+export declare function removeLabel(labelId: string): void;
+/**
+ * Update statistics metadata
+ *
+ * @param metadata - Statistics metadata
+ */
+export declare function updateStatisticsMetadata(metadata: StatisticMetadata[]): void;
+/**
+ * Update statistics data
+ *
+ * @param data - Statistics data points
+ */
+export declare function updateStatisticsData(data: StatisticData[]): void;

package/dist/core/store.d.ts

@@ -0,0 +1,64 @@
+/** Central reactive state store for sync-layer using SolidJS createStore. */
+import type { Connection } from "home-assistant-js-websocket";
+import type { SetStoreFunction, Store } from "solid-js/store";
+import type { CameraStreamData } from "../camera/types";
+import type { EntityHistoryData } from "../history/types";
+import type { WeatherForecastsData } from "../weather/types";
+import type { AreaId, AreaRegistryEntry, ConnectionState, DeviceId, DeviceRegistryEntry, EntityId, FloorId, FloorRegistryEntry, HassEntity, LabelId, LabelRegistryEntry, StatisticData, StatisticMetadata } from "./types";
+/**
+ * Complete state shape for the sync-layer store
+ *
+ * All updates use SolidJS store's produce() for mutations
+ * or reconcile() for bulk replacements.
+ *
+ * NOTE: No EntityIndices field -- indices are derived reactively in Plan 03.
+ * NOTE: No _activeSubscriptions -- managed externally.
+ */
+export interface GlassHomeState {
+    /** WebSocket connection instance */
+    conn: Connection | null;
+    /** Current connection state */
+    connectionState: ConnectionState;
+    /** Connection error (if any) */
+    connectionError: Error | null;
+    /** Home Assistant base URL */
+    hassUrl: string | null;
+    /** Live entity state (keyed by entity_id) */
+    entities: Record<EntityId, HassEntity>;
+    /** Entity registry entries (keyed by entity_id) */
+    entityRegistry: Record<EntityId, import("@glasshome/ha-types").EntityRegistryEntry>;
+    /** Device registry entries (keyed by device ID) */
+    devices: Record<DeviceId, DeviceRegistryEntry>;
+    /** Area registry entries (keyed by area ID) */
+    areas: Record<AreaId, AreaRegistryEntry>;
+    /** Floor registry entries (keyed by floor ID) */
+    floors: Record<FloorId, FloorRegistryEntry>;
+    /** Label registry entries (keyed by label ID) */
+    labels: Record<LabelId, LabelRegistryEntry>;
+    /** Statistics data (keyed by statistic_id) */
+    statistics: Record<string, StatisticData[]>;
+    /** Statistics metadata (keyed by statistic_id) */
+    statisticsMetadata: Record<string, StatisticMetadata>;
+    /** Entity history data (keyed by entity ID) */
+    history: Record<EntityId, EntityHistoryData>;
+    /** Weather forecasts data (keyed by entity ID) */
+    forecasts: Record<EntityId, WeatherForecastsData>;
+    /** Camera stream data (keyed by entity ID) */
+    streams: Record<EntityId, CameraStreamData>;
+}
+export declare const state: Store<GlassHomeState>;
+export declare const setState: SetStoreFunction<GlassHomeState>;
+/**
+ * Reset store to initial state
+ */
+export declare function resetStore(): void;
+/**
+ * Factory for testing isolation
+ *
+ * Creates a new, independent store instance for test isolation.
+ */
+export declare function createStoreInstance(): [GlassHomeState, SetStoreFunction<GlassHomeState>];
+/**
+ * Store tuple type for dependency injection
+ */
+export type Store = [get: GlassHomeState, set: SetStoreFunction<GlassHomeState>];