@webarray/esphome-native-api/dist/client/client.d.ts

TypeScript/Node.js client for ESPHome native API with encryption and deep sleep support

/**
 * ESPHome Native API Client
 * High-level client for interacting with ESPHome devices
 */
import { EventEmitter } from 'eventemitter3';
import { ConnectionOptions, DeviceInfo, EntityInfo, EntityCategory, EntityDomain, StateUpdate, BinarySensorState, SensorState, SwitchState, TextSensorState, LogEntry } from '../types';
export interface ClientEvents {
    connected: () => void;
    disconnected: (error?: Error) => void;
    error: (error: Error) => void;
    deviceInfo: (info: DeviceInfo) => void;
    logs: (entry: LogEntry) => void;
    state: (state: StateUpdate) => void;
    binarySensorState: (state: BinarySensorState) => void;
    sensorState: (state: SensorState) => void;
    switchState: (state: SwitchState) => void;
    textSensorState: (state: TextSensorState) => void;
    fanState: (state: any) => void;
    coverState: (state: any) => void;
    lightState: (state: any) => void;
    numberState: (state: any) => void;
    selectState: (state: any) => void;
    entity: (entity: EntityInfo) => void;
}
export declare class ESPHomeClient extends EventEmitter<ClientEvents> {
    private connection;
    private options;
    private deviceInfo?;
    private entities;
    private stateSubscriptions;
    private logSubscriptions;
    private isAuthenticating;
    constructor(options: ConnectionOptions);
    /**
     * Setup connection event handlers
     */
    private setupConnectionHandlers;
    /**
     * Connect to the ESPHome device
     */
    connect(): Promise<void>;
    /**
     * Disconnect from the device
     */
    disconnect(): void;
    /**
     * Perform the initial handshake
     */
    private performHandshake;
    /**
     * Send Hello request
     */
    private sendHelloRequest;
    /**
     * Handle Hello response
     */
    private handleHelloResponse;
    /**
     * Authenticate with the device
     */
    private authenticate;
    /**
     * Request device information
     */
    private requestDeviceInfo;
    /**
     * Get device information
     */
    getDeviceInfo(): DeviceInfo | undefined;
    /**
     * List all entities on the device
     */
    listEntities(): Promise<EntityInfo[]>;
    /**
     * Subscribe to state changes
     */
    subscribeStates(callback?: (state: StateUpdate) => void): void;
    /**
     * Unsubscribe from state changes
     */
    unsubscribeStates(callback?: (state: StateUpdate) => void): void;
    /**
     * Subscribe to logs
     */
    subscribeLogs(level?: number, callback?: (log: LogEntry) => void): void;
    /**
     * Unsubscribe from logs
     */
    unsubscribeLogs(callback?: (log: LogEntry) => void): void;
    /**
     * Get all entities of a specific type
     * @param type - Entity type filter (e.g., 'sensor', 'binary_sensor', 'switch')
     * @returns Array of entities matching the type
     */
    getEntitiesByType(type: EntityDomain | string): EntityInfo[];
    /**
     * Find entity by name or object ID
     * @param nameOrId - Entity name or object ID to search for
     * @returns First matching entity or undefined
     */
    findEntity(nameOrId: string): EntityInfo | undefined;
    /**
     * Find all entities matching a search term
     * @param searchTerm - Search term to match against name, object ID, or unique ID
     * @returns Array of matching entities
     */
    findEntities(searchTerm: string): EntityInfo[];
    /**
     * Get entity by key
     * @param key - Entity key
     * @returns Entity info or undefined if not found
     */
    getEntityByKey(key: number): EntityInfo | undefined;
    /**
     * Get entity state by key (requires state subscription to be active)
     * Note: This returns the last known state. Subscribe to states to receive updates.
     * @param key - Entity key
     * @returns Entity info for the key, or undefined if not found
     */
    getEntityInfo(key: number): EntityInfo | undefined;
    /**
     * Wait for an entity to appear during discovery
     * @param nameOrId - Entity name or object ID to wait for
     * @param timeout - Timeout in milliseconds (default: 30000)
     * @returns Promise that resolves with the entity info
     */
    waitForEntity(nameOrId: string, timeout?: number): Promise<EntityInfo>;
    /**
     * Get all entities
     * @returns Array of all entities
     */
    getAllEntities(): EntityInfo[];
    /**
     * Check if an entity exists
     * @param key - Entity key or name
     * @returns True if entity exists
     */
    hasEntity(key: number | string): boolean;
    /**
     * Get entity count
     * @returns Total number of entities
     */
    getEntityCount(): number;
    /**
     * Get entities by category
     * @param category - Entity category (EntityCategory.NONE, EntityCategory.CONFIG, or EntityCategory.DIAGNOSTIC)
     * @returns Array of entities in the specified category
     */
    getEntitiesByCategory(category: EntityCategory): EntityInfo[];
    /**
     * Switch command
     */
    switchCommand(key: number, state: boolean): Promise<void>;
    /**
     * Light command
     */
    lightCommand(key: number, options: any): Promise<void>;
    /**
     * Fan command
     */
    fanCommand(key: number, options: {
        state?: boolean;
        speed?: number;
        speedLevel?: number;
        oscillating?: boolean;
    }): Promise<void>;
    numberCommand(key: number, state: number): Promise<void>;
    selectCommand(key: number, state: string): Promise<void>;
    buttonCommand(key: number): Promise<void>;
    /**
     * Handle incoming messages
     */
    private handleMessage;
    /**
     * Handle GetTimeRequest from device
     */
    private handleGetTimeRequest;
    /**
     * Handle device info response
     */
    private handleDeviceInfoResponse;
    /**
     * Handle entity response
     */
    private handleEntityResponse;
    /**
     * Handle state response
     */
    private handleStateResponse;
    /**
     * Handle log response
     */
    private handleLogResponse;
    /**
     * Wait for a specific message type
     */
    private waitForMessage;
    /**
     * Encode a message using protobuf
     */
    private encodeMessage;
    /**
     * Decode a message using protobuf
     */
    private decodeMessage;
    /**
     * Destroy the client
     */
    destroy(): void;
    /**
     * Check if connected
     */
    isConnected(): boolean;
    /**
     * Check if authenticated
     */
    isAuthenticated(): boolean;
    /**
     * Get connection health metrics
     * @returns Health metrics including latency, uptime, and message counts
     */
    getHealthMetrics(): any;
    /**
     * Get connection health status with analysis
     * @returns Health status with metrics, status indicator, and identified issues
     */
    getConnectionHealth(): any;
    /**
     * Reset health metrics counters
     */
    resetHealthMetrics(): void;
    /**
     * Enable detailed logging
     * Sets DEBUG environment variable for this instance
     */
    enableDetailedLogging(): void;
    /**
     * Get connection metrics for debugging
     * @returns Object containing connection statistics
     */
    getConnectionMetrics(): {
        state: import("../types").ConnectionState;
        health: any;
        entityCount: number;
        subscriptions: {
            states: number;
            logs: number;
        };
    };
    /**
     * Capture protocol dump to console
     * Useful for debugging protocol issues
     * @param enable - Enable or disable protocol dumping
     */
    captureProtocolDump(enable?: boolean): void;
}
//# sourceMappingURL=client.d.ts.map