@glasshome/sync-layer 0.7.1 → 0.8.0

package/dist/commands/types.d.ts

@@ -1,113 +0,0 @@
-/**
- * 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

@@ -1,48 +0,0 @@
-/**
- * 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

@@ -1,126 +0,0 @@
-/**
- * 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. Redirects the whole page to the Home Assistant authorization page
- * 2. Waits for user authorization
- * 3. On return, HA redirects back to the app URL with `?auth_callback=1&code=…`
- * 4. Exchanges the authorization code for tokens and returns an 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
- *
- * In browser environments `getAuth` handles this automatically via a full-page
- * redirect (not a popup); native platforms supply `getAuthCode` instead.
- *
- * @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/bridged.d.ts

@@ -1,16 +0,0 @@
-import type { HaBridge } from "../worker/bridge-client";
-/**
- * Wire an HA bridge (worker-backed connection) into the store. The bridge's
- * facade rides the same load/subscribe pipeline as a direct socket; only the
- * lifecycle signals differ — they arrive as worker messages instead of
- * Connection events.
- *
- * Call after bridge.connect() resolved. Returns when initial data is loaded.
- */
-export declare function attachBridgeToStore(bridge: HaBridge, hassUrl: string, mediaProxyBase?: string): Promise<void>;
-/** Map worker connection-state messages onto the store. */
-export declare function applyBridgeConnState(state: "connected" | "disconnected" | "reconnecting"): void;
-/** Re-sync after the worker reports a completed reconnect. */
-export declare function reloadAfterBridgeReconnect(bridge: HaBridge): Promise<void>;
-/** Detach on shutdown; the caller terminates the worker itself. */
-export declare function detachBridgeFromStore(): void;

package/dist/connection/manager.d.ts

@@ -1,51 +0,0 @@
-/**
- * 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 HaLink } from "../core/store";
-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 link
- */
-export declare function getConnection(): HaLink | null;
-/**
- * Check if currently connected
- */
-export declare function isConnected(): boolean;
-/**
- * Get the underlying socket's connected flag.
- *
- * Exposed so apps can render a connection indicator in the UI. Distinct from
- * `isConnected()` which reflects the manager's internal lifecycle state.
- */
-export declare function getConnectionState(): boolean;
-export declare function loadInitialData(conn: Pick<HaLink, "sendMessagePromise">): Promise<void>;
-/**
- * Refresh all data
- */
-export declare function refreshData(): Promise<void>;

package/dist/connection/subscription-manager.d.ts

@@ -1,48 +0,0 @@
-/**
- * Entity Subscription Manager
- *
- * Ref-counted registry that tracks which entity IDs need live updates
- * from Home Assistant. When the active set changes, resubscribes with
- * the new entity_ids filter so HA only sends diffs for displayed entities.
- *
- * @packageDocumentation
- */
-import type { EntityId } from "../core/types";
-import type { SyncLayerConnection } from "./types";
-type UnsubscribeFn = () => Promise<void> | void;
-declare global {
-    var __GH_SYNC_LAYER_SUB_MGR__: boolean | undefined;
-}
-/**
- * Register an entity for live updates. Returns an unregister function.
- * Call from useEntity/useEntities hooks via onCleanup.
- */
-export declare function registerEntity(entityId: EntityId): () => void;
-/**
- * Get the current set of actively subscribed entity IDs.
- */
-export declare function getActiveEntityIds(): Set<EntityId>;
-/**
- * Set the connection reference used for resubscribing.
- */
-export declare function setManagerConnection(connection: SyncLayerConnection): void;
-/**
- * Set the resubscribe callback. Called by subscriptions.ts to wire
- * the manager into the actual WS subscription lifecycle.
- */
-export declare function setResubscribeHandler(handler: (conn: SyncLayerConnection, entityIds: EntityId[]) => Promise<UnsubscribeFn>): void;
-/**
- * Store the current entity subscription's unsub function.
- * Called after initial subscribe_entities.
- */
-export declare function setCurrentEntityUnsub(unsub: UnsubscribeFn): void;
-/**
- * Force a resubscribe with the current active set.
- * Used on reconnect.
- */
-export declare function forceResubscribe(): Promise<void>;
-/**
- * Reset manager state. Used on disconnect or for testing.
- */
-export declare function resetManager(): void;
-export {};

package/dist/connection/subscriptions.d.ts

@@ -1,31 +0,0 @@
-/**
- * Event Subscriptions
- *
- * Sets up WebSocket event subscriptions to keep state in sync
- * with Home Assistant.
- *
- * @packageDocumentation
- */
-import type { EntityId } from "../core/types";
-import type { SyncLayerConnection } from "./types";
-/**
- * Subscribe to entity state updates with an entity_ids filter.
- * Called by the subscription manager on flush.
- */
-export declare function subscribeEntities(connection: SyncLayerConnection, entityIds: EntityId[]): Promise<() => Promise<void>>;
-/**
- * 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

@@ -1,151 +0,0 @@
-/**
- * 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";
-/**
- * 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;
-}

package/dist/core/privileged-conn.d.ts

@@ -1,29 +0,0 @@
-/**
- * The privileged Home Assistant connection, held outside the shared store.
- *
- * This handle tunnels arbitrary HA traffic: the worker's `case "send"` forwards
- * whatever arrives on it after a shape check only, because capability
- * validation belongs on the per-widget MessagePorts, not here.
- *
- * It therefore must not be reachable from widget code. It used to live at
- * `state.conn`, and `state` is exported from this package's entry, which the
- * host serves to every widget bundle through its import map — so any widget
- * could read the handle and call any service on any entity, regardless of the
- * capabilities it declared and the user approved. Proven by execution, not
- * argued: a widget-side `useService()` emitted `call_service`/`lock.unlock`
- * onto the host's own channel (finding 46).
- *
- * Module-local and deliberately absent from `src/index.ts`. Not being exported
- * is the entire mechanism, so exporting it — directly, or by parking the value
- * on anything that is exported — reopens the hole. `check-widget-reachable-
- * surface.ts` fails the build if it ever becomes reachable again.
- *
- * Plain variable rather than store state: every reader takes it imperatively
- * inside an async fetcher or command, so none of them tracked it reactively.
- * `state.connectionState` remains the reactive signal for connection status.
- */
-import type { HaLink } from "./store";
-/** Read the live connection. Null before connect and after disconnect. */
-export declare function privilegedConn(): HaLink | null;
-/** Set by the connection layer on connect/disconnect. Host-side callers only. */
-export declare function setPrivilegedConn(conn: HaLink | null): void;