freeathome-local-api-client/dist/index.d.ts

A client library for the BUSCH-JAEGER free@home local API implemented in TypeScript

import { EventEmitter } from 'node:events';
import { SchedulerLike, Observable } from 'rxjs';

/** Describes an input or output. */
interface InOutPut {
    /** The input or output value. */
    value?: string;
    /** The pairing ID. */
    pairingID?: number;
}

/** Describes a device channel */
interface Channel {
    /** The channel display name. */
    displayName?: string;
    /** The function identifier. */
    functionID?: string;
    /** The room to which the channel is mapped. */
    room?: string;
    /** The floor to which the channel is mapped.  */
    floor?: string;
    /** The inputs provided by the channel. */
    inputs?: {
        /** The input identified by a string key. */
        [key: string]: InOutPut;
    };
    /** The output provided by the channel. */
    outputs?: {
        /** The output identified by a string key. */
        [key: string]: InOutPut;
    };
    /** The channel parameters. */
    parameters?: {
        /** The channel parameters identified by a string key. */
        [key: string]: string;
    };
    /** The channel type. */
    type?: string;
}

/** Describes a device */
interface Device {
    /** The device display name */
    displayName?: string;
    /** The room to which the device is mapped. */
    room?: string;
    /** The floor to which the device is mapped. */
    floor?: string;
    /** The device interface. */
    interface?: string;
    /** The device's native identifier. */
    nativeId?: string;
    /** The channels provided by the device. */
    channels?: {
        /** The channel identified by a string key. */
        [key: string]: Channel;
    };
    /** The device parameters. */
    parameters?: {
        /** The parameter identified by a string key. */
        [key: string]: string;
    };
}

/** Describes a list of Devices identified by their serial. */
interface Devices {
    /**
     * The device connected to the system access point identified by the key.
     */
    [key: string]: Device;
}

/** Describes the rooms collection. */
interface Rooms {
    /** The room names on the floor identified by the key. */
    [key: string]: {
        /** The room name. */
        name: string;
    };
}

/** Describes the floor collection. */
interface Floors {
    /** The floor identified by the key. */
    [key: string]: {
        /** The floor name. */
        name: string;
        /** The rooms on the floor. */
        rooms: Rooms;
    };
}

/** Describes the user collection. */
interface Users {
    /** The user properties for the user identified by the key. */
    [key: string]: {
        /** Determines whether or not the user account is enabled. */
        enabled: boolean;
        /** An array of flags for the user account. */
        flags: Array<string>;
        /** An array of the permissions granted to the user. */
        grantedPermissions: Array<string>;
        /** The user's JID. */
        jid: string;
        /** The users name. */
        name: string;
        /** The array of the permissions requested by the user. */
        requestedPermissions: Array<string>;
        /** The user's role. */
        role: string;
    };
}

/** Describes a system access point. */
interface SysAP {
    /** The devices connected to the system access point. */
    devices: Devices;
    /** The floorplan */
    floorplan: {
        floors: Floors;
    };
    /** The name of the system access point. */
    sysapName: string;
    /** The users. */
    users: Users;
    /** An error, if an error is available for the system access point. */
    error?: Error;
}

/** Describes system access point configurations. */
interface Configuration {
    /** The system access point identified by it's UUID. */
    [key: string]: SysAP;
}

/**
 * Describes a system access point device list.
 * @interface
 */
interface DeviceList {
    /**
     * An array of the device serials connected to the system access point identified by the key.
     */
    [key: string]: Array<string>;
}

/** Describes the response to a device request. */
interface DeviceResponse {
    /**
     * The requested devices connected to the system access point identified by the key.
     */
    [key: string]: {
        devices: Devices;
    };
}

/** Describes an error. */
interface Error$1 {
    /**
     * The error code
     * @example "2010"
     */
    code: string;
    /**
     * A detailed message describing the error
     * @example "FreeAtHome connection timeout"
     */
    detail: string;
    /**
     * The title for the error
     * @example "Connection Error"
     */
    title: string;
}

/** Describes the response to a query requesting a data point. */
interface GetDataPointResponse {
    /** The response to the data points requested by the system access point identified by the key. */
    [key: string]: {
        /** The array of responses. */
        values: Array<string>;
    };
}

/** Describes the interface a logger has to provide to be usable for the library. */
interface Logger {
    /**
     * Logs a debug message.
     * @param message The message to be logged.
     * @param optionalParams An optional array of parameters to be included in the log entry.   *
     */
    debug: (message?: unknown, ...optionalParams: unknown[]) => void;
    /**
     * Logs a error message.
     * @param message The message to be logged.
     * @param optionalParams An optional array of parameters to be included in the log entry.   *
     */
    error: (message?: unknown, ...optionalParams: unknown[]) => void;
    /**
     * Logs a informational message.
     * @param message The message to be logged.
     * @param optionalParams An optional array of parameters to be included in the log entry.   *
     */
    log: (message?: unknown, ...optionalParams: unknown[]) => void;
    /**
     * Logs a warning message.
     * @param message The message to be logged.
     * @param optionalParams An optional array of parameters to be included in the log entry.   *
     */
    warn: (message?: unknown, ...optionalParams: unknown[]) => void;
}

/**
 * Describes the ScenesTriggered object that is included in the web socket message.
 * @see WebSocketMessage
 */
interface ScenesTriggered {
    /** The channels affected by the scene identified by the key. */
    [key: string]: {
        /** The channel */
        channels: {
            /** The outputs affected by the channel identified by the key. */
            [key: string]: {
                /** The outputs */
                outputs: {
                    /** The output value and pairing ID affected by the output identified by the key. */
                    [key: string]: {
                        /** The output value. */
                        value: string;
                        /** The pairing ID. */
                        pairingID: number;
                    };
                };
            };
        };
    };
}

/** Describes a response to a request setting a new value for a data point. */
interface SetDataPointResponse {
    /** The response to the data point request for the system access point identified by the key. */
    [key: string]: {
        /** The response to the requested datra point identified by the key. */
        [key: string]: string;
    };
}

/**
 * Represents a message that was received from the System Access Point web socket.
 */
interface WebSocketMessage {
    /** The update message for the system access point identified by the key. */
    [key: string]: {
        /** The data points. */
        datapoints: {
            /** The value of the data point identified by the key. */
            [key: string]: string;
        };
        /** The devices. */
        devices: Devices;
        /** The array of device serials representing the devices added to the system access point. */
        devicesAdded: Array<string>;
        /** The array of device serials representing the devices removed from the system access point. */
        devicesRemoved: Array<string>;
        /** The triggered scenes. */
        scenesTriggered: ScenesTriggered;
        /** The message parameters. */
        parameters?: {
            [key: string]: string;
        };
    };
}

/** Describes a response to a request creating a new virtual device. */
interface VirtualDeviceResponse {
    /** The response to a virtual device request for the system access point identified by the key. */
    [key: string]: {
        /** The devices */
        devices: {
            /** The created device identified by the key. */
            [key: string]: {
                /** The device serial. */
                serial: string;
            };
        };
    };
}

/** Defines a virtual device. */
interface VirtualDevice {
    /** The virtual device type. */
    type: VirtualDeviceType;
    /** The virtual device properties */
    properties?: {
        /** The time to live value indicates the number of seconds the system access point will wait for a message before it assumes the device to be unresponsive. */
        ttl?: string;
        /** The display name for the virtual device. */
        displayname?: string;
        /** The virtual device flavor. */
        flavor?: string;
        /** The virtual device capabilities. */
        capabilities?: Array<number>;
    };
}
/** Defines the possible types of virtual devices. */
declare enum VirtualDeviceType {
    /** A binary sensor */
    BinarySensor = "BinarySensor",
    /** A blind actuator */
    BlindActuator = "BlindActuator",
    /** A switching actuator */
    SwitchingActuator = "SwitchingActuator",
    /** A ceiling fan actuator */
    CeilingFanActuator = "CeilingFanActuator",
    /** A real time clock */
    RTC = "RTC",
    /** A dimmer actuator */
    DimActuator = "DimActuator",
    /** A charger for an electronic vehicle */
    EVCharging = "evcharging",
    /** A window sensor */
    WindowSensor = "WindowSensor",
    /** A simple door lock */
    SimpleDoorlock = "simple_doorlock",
    /** A shutter actuator */
    ShutterActuator = "ShutterActuator",
    /** A weather station */
    WeatherStation = "WeatherStation",
    /** A temperature sensor */
    WeatherTemperatureSensor = "Weather-TemperatureSensor",
    /** A wind sensor */
    WeatherWindSensor = "Weather-WindSensor",
    /** A brightness sensor */
    WeatherBrightnessSensor = "Weather-BrightnessSensor",
    /** A rain sensor */
    WeatherRainSensor = "Weather-RainSensor",
    /** A window actuator */
    WindowActuator = "WindowActuator",
    /** A detector for carbon monoxide (CO) */
    CODetector = "CODetector",
    /** A fire detector */
    FireDetector = "FireDetector",
    /** A KNX switch sensor */
    KNXSwitchSensor = "KNX-SwitchSensor",
    /** A media player */
    MediaPlayer = "MediaPlayer",
    /** A battery */
    EnergyBattery = "EnergyBattery",
    /** An inverter */
    EnergyInverter = "EnergyInverter",
    /** An energy meter */
    EnergyMeter = "EnergyMeter",
    /** A device combining inverter and battery characteristics */
    EnergyInverterBattery = "EnergyInverterBattery",
    /** A device combining inverter and energy meter characteristics */
    EnergyInverterMeter = "EnergyInverterMeter",
    /** A device combining inverter, battery and energy meter characteristics */
    EnergyInverterMeterBattery = "EnergyInverterMeterBattery",
    /** A device combining battery and energy meter characteristics */
    EnergyMeterBattery = "EnergyMeterBattery",
    /** An air quality sensor measuring carbon dioxide (CO2) */
    AirQualityCO2 = "AirQualityCO2",
    /** An air quality sensor measuring carbon monoxide (CO) */
    AirQualityCO = "AirQualityCO",
    /** An full air quality sensor */
    AirQualityFull = "AirQualityFull",
    /** An air quality sensor measuring humidity */
    AirQualityHumidity = "AirQualityHumidity",
    /** An air quality sensor measuring nitrogen dioxide (NO2) */
    AirQualityNO2 = "AirQualityNO2",
    /** An air quality sensor measuring ozone (O3) */
    AirQualityO3 = "AirQualityO3",
    /** An air quality sensor measuring coarse particulate matter with in the 10 micron scale */
    AirQualityPM10 = "AirQualityPM10",
    /** An air quality sensor measuring coarse particulate matter with in the 25 micron scale */
    AirQualityPM25 = "AirQualityPM25",
    /** An air quality sensor measuring barometric pressure */
    AirQualityPressure = "AirQualityPressure",
    /** An air quality sensor measuring temperature */
    AirQualityTemperature = "AirQualityTemperature",
    /** An air quality sensor measuring volatile organic compounds */
    AirQualityVOC = "AirQualityVOC",
    /** A version 2 energy meter */
    EnergyMeterV2 = "EnergyMeterv2",
    HomeApplianceLaundry = "HomeAppliance-Laundry",
    HVAC = "HVAC",
    SplitUnit = "SplitUnit"
}

/**
 * Determines whether the specified object is a web socket message.
 * @param obj {object} The object to be tested
 * @param logger {Logger} The logger instance to be used.
 * @param verbose {boolean} Determines whether validation errors shall be logged. Default value is false.
 * @returns {boolean} A value indicating whether the specified object is a web socket message.
 */
declare function isWebSocketMessage(obj: unknown, logger: Logger, verbose?: boolean): obj is WebSocketMessage;
/**
 * Determines whether the specified object is a configuration.
 * @param obj {object} The object to be tested
 * @param logger {Logger} The logger instance to be used.
 * @param verbose {boolean} Determines whether validation errors shall be logged. Default value is false.
 * @returns {boolean} A value indicating whether the specified object is a configuration.
 */
declare function isConfiguration(obj: unknown, logger: Logger, verbose?: boolean): obj is Configuration;
/**
 * Determines whether the specified object is a device list.
 * @param obj {object} The object to be tested
 * @param logger {Logger} The logger instance to be used.
 * @param verbose {boolean} Determines whether validation errors shall be logged. Default value is false.
 * @returns {boolean} A value indicating whether the specified object is a device list.
 */
declare function isDeviceList(obj: unknown, logger: Logger, verbose?: boolean): obj is DeviceList;
/**
 * Determines whether the specified object is a device response.
 * @param obj {object} The object to be tested
 * @param logger {Logger} The logger instance to be used.
 * @param verbose {boolean} Determines whether validation errors shall be logged. Default value is false.
 * @returns {boolean} A value indicating whether the specified object is a device response.
 */
declare function isDeviceResponse(obj: unknown, logger: Logger, verbose?: boolean): obj is DeviceResponse;
/**
 * Determines whether the specified object is a valid response to a get data point request.
 * @param obj {object} The object to be tested
 * @param logger {Logger} The logger instance to be used.
 * @param verbose {boolean} Determines whether validation errors shall be logged. Default value is false.
 * @returns {boolean} A value indicating whether the specified object is a response to a get data point request.
 */
declare function isGetDataPointResponse(obj: unknown, logger: Logger, verbose?: boolean): obj is GetDataPointResponse;
/**
 * Determines whether the specified object is a valid response to a set data point request.
 * @param obj {object} The object to be tested
 * @param logger {Logger} The logger instance to be used.
 * @param verbose {boolean} Determines whether validation errors shall be logged. Default value is false.
 * @returns {boolean} A value indicating whether the specified object is a response to a set data point request.
 */
declare function isSetDataPointResponse(obj: unknown, logger: Logger, verbose?: boolean): obj is SetDataPointResponse;
/**
 * Determines whether the specified object is a virtual device.
 * @param obj {object} The object to be tested
 * @param logger {Logger} The logger instance to be used.
 * @param verbose {boolean} Determines whether validation errors shall be logged. Default value is false.
 * @returns {boolean} A value indicating whether the specified object is a virtual device.
 */
declare function isVirtualDevice(obj: unknown, logger: Logger, verbose?: boolean): obj is VirtualDevice;
/**
 * Determines whether the specified object is a virtual device response.
 * @param obj {object} The object to be tested
 * @param logger {Logger} The logger instance to be used.
 * @param verbose {boolean} Determines whether validation errors shall be logged. Default value is false.
 * @returns {boolean} A value indicating whether the specified object is a response to a virtual device request.
 */
declare function isVirtualDeviceResponse(obj: unknown, logger: Logger, verbose?: boolean): obj is VirtualDeviceResponse;
/**
 * Determines whether the specified object is a channel.
 * @param obj {object} The object to be tested
 * @param logger {Logger} The logger instance to be used.
 * @param verbose {boolean} Determines whether validation errors shall be logged. Default value is false.
 * @returns {boolean} A value indicating whether the specified object is a channel.
 */
declare function isChannel(obj: unknown, logger: Logger, verbose?: boolean): obj is Channel;
/**
 * Determines whether the specified object is a device.
 * @param obj {object} The object to be tested
 * @param logger {Logger} The logger instance to be used.
 * @param verbose {boolean} Determines whether validation errors shall be logged. Default value is false.
 * @returns {boolean} A value indicating whether the specified object is a device.
 */
declare function isDevice(obj: unknown, logger: Logger, verbose?: boolean): obj is Device;

/** The class representing a System Access Point. */
declare class SystemAccessPoint extends EventEmitter {
    private readonly hostName;
    readonly userName: string;
    readonly password: string;
    private readonly tlsEnabled;
    private readonly verboseErrors;
    private readonly logger;
    readonly scheduler?: SchedulerLike | undefined;
    /** The basic authentication key used for requests. */
    readonly basicAuthKey: string;
    private webSocket?;
    private readonly webSocketMessageSubject;
    private readonly webSocketKeepaliveTimerReset$;
    private readonly webSocketKeepaliveTimer$;
    private webSocketKeepaliveSubscription?;
    /**
     * Constructs a new SystemAccessPoint instance
     *
     * @constructor
     * @param hostName {string} The system access point host name.
     * @param userName {string} The user name that shall be used to authenticate with the system access point.
     * @param password {string} The password that shall be used to authenticate with the system access point.
     * @param tlsEnabled {boolean} Determines whether the communication with the system access point shall be protected by TLS.
     * @param verboseErrors {boolean} Determines whether verbose error messages shall be used, for example for message validation.
     * @param logger {Logger} The logger instance to be used. If no explicit implementation is provided, the this.logger will be used for logging.
     */
    constructor(hostName: string, userName: string, password: string, tlsEnabled?: boolean, verboseErrors?: boolean, logger?: Logger, scheduler?: SchedulerLike | undefined);
    /**
     * Connects to the System Access Point web socket.
     * @param certificateVerification {boolean} Determines whether the TLS certificate presented by the server will be verified.
     */
    connectWebSocket(certificateVerification?: boolean): void;
    /**
     * Creates a new virtual device.
     * @param sysApUuid {string} The UUID identifying the system access point.
     * @param deviceSerial {string} The serial number to be assigned to the device.
     * @param virtualDevice {VirtualDevice} The virtual device to be created.
     * @returns {Promise.<VirtualDeviceResponse>} The response to the virtual device request.
     */
    createVirtualDevice(sysApUuid: string, deviceSerial: string, virtualDevice: VirtualDevice): Promise<VirtualDeviceResponse>;
    private createWebSocket;
    /**
     * Disconnects from the System Access Point web socket.
     * @param force {boolean} Determines whether or not the connection will be closed forcibly.
     */
    disconnectWebSocket(force?: boolean): void;
    /**
     * Gets the configuration from the system access point.
     * @returns {Promise.<Configuration>} The system access point configuration.
     */
    getConfiguration(): Promise<Configuration>;
    /**
     * Gets the device list from the system access point.
     * @returns {Promise.<DeviceList>} The requested device list.
     */
    getDeviceList(): Promise<DeviceList>;
    /**
     * Gets the specified device from the system access point.
     * @param sysApUuid {string} The UUID identifying the system access point.
     * @param deviceSerial {string} The device serial number.
     * @returns {Promise.<DeviceResponse>} The response to the device request.
     */
    getDevice(sysApUuid: string, deviceSerial: string): Promise<DeviceResponse>;
    /**
     * Gets the specified data point from the system access point.
     * @param sysApUuid {string} The UUID idenfifying the system access point.
     * @param deviceSerial {string} The device serial number.
     * @param channel {string} The channel identifier.
     * @param dataPoint {string} The datapoint identifier.
     * @returns {Promise.<GetDataPointResponse>} The response to the get data point request.
     */
    getDatapoint(sysApUuid: string, deviceSerial: string, channel: string, dataPoint: string): Promise<GetDataPointResponse>;
    /**
     * Gets the web socket messages.
     * @returns {Observable.<WebSocketMessage>} An observable that is updated with the messages received from the web socket.
     */
    getWebSocketMessages(): Observable<WebSocketMessage>;
    /**
     * Sets a new value for the specificed data point.
     * @param sysApUuid {string} The UUID idenfifying the system access point.
     * @param deviceSerial {string} The device serial number.
     * @param channel {string} The channel identifier.
     * @param dataPoint {string} The datapoint identifier.
     * @param value {string} The new value to be set.
     * @returns {Promise.<SetDataPointResponse>} The response to the set data point request.
     */
    setDatapoint(sysApUuid: string, deviceSerial: string, channel: string, dataPoint: string, value: string): Promise<SetDataPointResponse>;
    /**
     * Triggeres the given action for the specified proxy device. Please note that this method is part of the experimental API!
     * @param sysApUuid {string} The UUID idenfifying the system access point.
     * @param deviceClass {string} The device class.
     * @param deviceSerial {string} The device serial number.
     * @param action {string} The action to be triggered.
     * @returns {Promise.<DeviceResponse>} The response to the request.
     */
    triggerProxyDevice(sysApUuid: string, deviceClass: string, deviceSerial: string, action: string): Promise<DeviceResponse>;
    /**
     * Sets the given value for the specified proxy device. Please note that this method is part of the experimental API!
     * @param sysApUuid {string} The UUID idenfifying the system access point.
     * @param deviceClass {string} The device class.
     * @param deviceSerial {string} The device serial number.
     * @param value {string} The value to be set.
     * @returns {Promise.<DeviceResponse>} The response to the request.
     */
    setProxyDeviceValue(sysApUuid: string, deviceClass: string, deviceSerial: string, value: string): Promise<DeviceResponse>;
    private fetchDataViaRest;
    private processRestResponse;
    private processWebSocketMessage;
}

export { type Channel, type Configuration, type Device, type DeviceList, type DeviceResponse, type Devices, type Error$1 as Error, type Floors, type GetDataPointResponse, type InOutPut, type Logger, type Rooms, type ScenesTriggered, type SetDataPointResponse, type SysAP, SystemAccessPoint, type Users, type VirtualDevice, type VirtualDeviceResponse, VirtualDeviceType, type WebSocketMessage, isChannel, isConfiguration, isDevice, isDeviceList, isDeviceResponse, isGetDataPointResponse, isSetDataPointResponse, isVirtualDevice, isVirtualDeviceResponse, isWebSocketMessage };