hoffmation-base 3.0.0-alpha.8 → 3.0.0-alpha.80

package/lib/server/services/api/api-service.d.ts

@@ -1,111 +1,158 @@
 import { BaseGroup, ButtonPosition, ButtonPressType, iBaseDevice } from '../../devices';
-import { CollisionSolving, DeviceSettings, RoomBase } from '../../../models';
+import { ActuatorSetStateCommand, BlockAutomaticCommand, BlockAutomaticLiftBlockCommand, CollisionSolving, DeviceSettings, DimmerSetLightCommand, LampSetLightCommand, LedSetLightCommand, RoomBase, ShutterSetLevelCommand } from '../../../models';
 import { LogObject } from '../log-service';
 import { AcDevice, AcMode } from '../ac';
 import { GroupSettings } from '../../../models/groupSettings/groupSettings';
 export declare class API {
     /**
      * Endpoint to end a scene manually (or early if it has automatic turn off)
-     * @param {string} deviceId
-     * @returns {Error | null}
+     * @param deviceId - The id of the scene to end
+     * @returns In case it failed the Error containing the reason
      */
     static endScene(deviceId: string): Error | null;
     /**
      * Gets the instance of an Ac Device identified by id
-     * @param {string} id
-     * @returns {OwnDaikinDevice | undefined}
+     * @param id - The device id of the AC
+     * @returns The instance of the AC Device or undefined if not found
      */
     static getAc(id: string): AcDevice | undefined;
     static getDevices(): {
         [id: string]: iBaseDevice;
     };
-    static getDevice(id: string): iBaseDevice;
+    static getDevice(id: string, warnIfNotFound?: boolean): iBaseDevice;
     static getGroup(id: string): BaseGroup | undefined;
     static getRooms(): Map<string, RoomBase>;
     static getRoom(id: string): RoomBase | undefined;
     static getLog(): LogObject[];
     /**
      * Turns on/off one AC identified by it's id
-     * @param id The id of the device, if wrong false will be returned
-     * @param {boolean} desiredState
-     * @param {AcMode} desiredMode
-     * @param desiredTemperature
-     * @param forceTime The time in ms this should not change before automatic change is allowed again
+     * @param id - The id of the device, if wrong false will be returned
+     * @param desiredState - The desired state for the AC
+     * @param desiredMode - The desired mode for the AC
+     * @param desiredTemperature - The desired temperature for the AC in Celsius
+     * @param forceTime - The time in ms this should not change before automatic change is allowed again
+     * @returns True if the AC was found and the state was changed
      */
     static setAc(id: string, desiredState: boolean, desiredMode?: AcMode, desiredTemperature?: number, forceTime?: number): boolean;
     /**
      * Turns on/off all AC´s in the home
-     * @param {boolean} desiredState
+     * @param desiredState - The desired state for all AC´s
      */
     static setAllAc(desiredState: boolean): void;
     /**
      * Changes the status of a given Lamp
-     * @param {string} deviceId The device Id of the lamp
-     * @param {boolean} state The desired new state
-     * @param timeout Desired time after which this should be reverted to normal state
-     * @returns {Error | null} In case it failed the Error containing the reason
+     * @param deviceId - The device Id of the lamp
+     * @param state - The desired new state
+     * @param timeout - Desired time after which this should be reverted to normal state
+     * @returns In case it failed the Error containing the reason
+     * @deprecated Use {@link API.lampSetLight} instead
+     * TODO: Remove deprecated API method
      */
     static setLamp(deviceId: string, state: boolean, timeout?: number): Error | null;
+    /**
+     * Changes the status of a given Lamp
+     * @param deviceId - The device Id of the lamp
+     * @param c - The command(stack) to perform on the lamp
+     * @returns In case it failed the Error containing the reason.
+     */
+    static lampSetLight(deviceId: string, c: LampSetLightCommand): Error | null;
     /**
      * Changes the status of a given actuator
-     * @param {string} deviceId The device Id of the actuator
-     * @param {boolean} state The desired new state
-     * @param timeout Desired time after which this should be reverted to automatic state
-     * @returns {Error | null} In case it failed the Error containing the reason
+     * @param deviceId - The device Id of the actuator
+     * @param state - The desired new state
+     * @param timeout - Desired time after which this should be reverted to automatic state
+     * @returns In case it failed the Error containing the reason
+     * @deprecated Use {@link API.actuatorSetState} instead
+     * TODO: Remove deprecated API method
      */
     static setActuator(deviceId: string, state: boolean, timeout?: number): Error | null;
     /**
      * Changes the status of a given actuator
-     * @param {string} deviceId The device Id of the actuator
-     * @param {boolean} state The desired new state
-     * @param timeout A chosen Timeout after which the light should be reset
-     * @param brightness The desired brightness
-     * @param transitionTime The transition time during turnOn/turnOff
-     * @returns {Error | null} In case it failed the Error containing the reason
+     * @param deviceId - The device Id of the actuator
+     * @param c - The command(stack) to perform on the actuator
+     * @returns In case it failed the Error containing the reason
+     */
+    static actuatorSetState(deviceId: string, c: ActuatorSetStateCommand): Error | null;
+    /**
+     * Changes the status of the given dimmer
+     * @param deviceId - The device Id of the actuator
+     * @param state - The desired new state
+     * @param timeout - A chosen Timeout after which the light should be reset
+     * @param brightness - The desired brightness
+     * @param transitionTime - The transition time during turnOn/turnOff
+     * @returns In case it failed the Error containing the reason
+     * @deprecated Use {@link API.dimmerSetLight} instead
+     * TODO: Remove deprecated API method
      */
     static setDimmer(deviceId: string, state: boolean, timeout?: number, brightness?: number, transitionTime?: number): Error | null;
     /**
-     * Changes the status of a given actuator
-     * @param {string} deviceId The device Id of the actuator
-     * @param {boolean} state The desired new state
-     * @param timeout A chosen Timeout after which the light should be reset
-     * @param brightness The desired brightness
-     * @param transitionTime The transition time during turnOn/turnOff
-     * @param {string} color The desired color in 6 digit hex Code
-     * @param {number} colorTemp The desired color Temperature (0 = more White)
-     * @returns {Error | null} In case it failed the Error containing the reason
+     * Changes the status of the given dimmer
+     * @param deviceId - The device Id of the dimmable device.
+     * @param command - The command(stack) to perform on the dimmer
+     * @returns In case it failed the Error containing the reason.
+     */
+    static dimmerSetLight(deviceId: string, command: DimmerSetLightCommand): Error | null;
+    /**
+     * Changes the status of a given led-device
+     * @param deviceId - The device Id of the actuator
+     * @param state - The desired new state
+     * @param timeout - A chosen Timeout after which the light should be reset
+     * @param brightness - The desired brightness
+     * @param transitionTime - The transition time during turnOn/turnOff
+     * @param color - The desired color in 6 digit hex Code
+     * @param colorTemp - The desired color Temperature (0 = more White)
+     * @returns In case it failed the Error containing the reason
+     * @deprecated Use {@link API.ledSetLight} instead
+     * TODO: Remove deprecated API method
      */
     static setLedLamp(deviceId: string, state: boolean, timeout?: number, brightness?: number, transitionTime?: number, color?: string, colorTemp?: number): Error | null;
+    /**
+     * Changes the status of a given led-device
+     * @param deviceId - The device Id of the LED-Device
+     * @param command - The command(stack) to perform on the led-device
+     * @returns In case it failed the Error containing the reason
+     */
+    static ledSetLight(deviceId: string, command: LedSetLightCommand): Error | null;
     /**
      * Changes the position of a given shutter
      * if needed this updates the window position as well
-     * @param {string} deviceId The device Id of the shutter
-     * @param {number} level The desired new level (0 being open, 100 being closed)
-     * @returns {Error | null} Error if there is no shutter with the given id
+     * @param deviceId - The device Id of the shutter
+     * @param level - The desired new level (0 being open, 100 being closed)
+     * @returns Error if there is no shutter with the given id
+     * @deprecated Use {@link API.shutterSetLevel} instead
+     * TODO: Remove deprecated API method
      */
     static setShutter(deviceId: string, level: number): Error | null;
+    /**
+     * Changes the position of a given shutter
+     * if needed this updates the window position as well
+     * @param deviceId - The device Id of the shutter
+     * @param command - The command(stack) to perform on the shutter
+     * @returns Error if there is no shutter with the given id
+     */
+    static shutterSetLevel(deviceId: string, command: ShutterSetLevelCommand): Error | null;
     static speakOnDevice(deviceId: string, message: string, volume?: number): Error | null;
     /**
      * Starts a specified scene
-     * @param {string} deviceId The targeted scene
-     * @param {number} turnOffTimeout If provided the time in ms after which the scene should end automatically
-     * @returns {Error | null} In case it failed the Error containing the reason
+     * @param deviceId - The targeted scene
+     * @param turnOffTimeout - If provided the time in ms after which the scene should end automatically
+     * @returns In case it failed the Error containing the reason
      */
     static startScene(deviceId: string, turnOffTimeout?: number): Error | null;
     static switchGarageDoor(deviceId: string, open: boolean): Error | null;
     /**
      * Changes the settings of a given device
-     * @param {string} deviceId The id of the device to change the settings
-     * @param settings A partial settings object containing the wanted settings properties
-     * @returns {Error | null} In case it failed the Error containing the reason
+     * @param deviceId - The id of the device to change the settings
+     * @param settings - A partial settings object containing the wanted settings properties
+     * @returns In case it failed the Error containing the reason
      */
     static setDeviceSettings(deviceId: string, settings: Partial<DeviceSettings>): Error | null;
     static setGroupSettings(groupId: string, settings: Partial<GroupSettings>): Error | null;
     /**
      * Changes the settings of a given room
-     * @param {string} roomName The id of the Room to change the settings
-     * @param settings A partial settings object containing the wanted settings properties
-     * @returns {Error | null} In case it failed the Error containing the reason
+     * @param roomName - The id of the Room to change the settings
+     * @param settings - A partial settings object containing the wanted settings properties
+     * @returns In case it failed the Error containing the reason
      */
     static setRoomSettings(roomName: string, settings: Partial<DeviceSettings>): Error | null;
     static getLastCameraImage(deviceId: string): Error | string;
@@ -113,17 +160,35 @@ export declare class API {
     static loadAllDeviceSettingsFromDb(): void;
     /**
      * Lifts a previously started Block of automatic
-     * @param {string} deviceId The target device
-     * @returns {Error | null} In case it failed the Error containing the reason
+     * @param deviceId - The target device
+     * @returns In case it failed the Error containing the reason
+     * @deprecated Use {@link API.blockAutomaticLiftAutomaticBlock} instead
+     * TODO: V4 Remove deprecated API method
      */
     static liftAutomaticBlock(deviceId: string): Error | null;
+    /**
+     * Lifts a previously started Block of automatic
+     * @param deviceId - The target device
+     * @param command - The command to lift the automatic block
+     * @returns In case it failed the Error containing the reason
+     */
+    static blockAutomaticLiftAutomaticBlock(deviceId: string, command: BlockAutomaticLiftBlockCommand): Error | null;
     /**
      * Blocks the automatic of the given device for provided Duration
-     * @param {string} deviceId The target device
-     * @param {number} duration The duration in ms for which the device should remain in current state
-     * @param {CollisionSolving} onCollision The desired Collision Solving strategy, in case the automatic being blocked already
-     * @returns {Error | null} In case it failed the Error containing the reason
+     * @param deviceId - The target device
+     * @param duration - The duration in ms for which the device should remain in current state
+     * @param onCollision - The desired Collision Solving strategy, in case the automatic being blocked already
+     * @returns In case it failed the Error containing the reason
+     * @deprecated Use {@link API.blockAutomaticSetBlock} instead
+     * TODO: Remove deprecated API method
      */
     static blockAutomatic(deviceId: string, duration: number, onCollision?: CollisionSolving): Error | null;
+    /**
+     * Blocks the automatic of the given device for provided Duration
+     * @param deviceId - The target device
+     * @param command - The command to block the automatic
+     * @returns In case it failed the Error containing the reason
+     */
+    static blockAutomaticSetBlock(deviceId: string, command: BlockAutomaticCommand): Error | null;
     static pressButtonSwitch(deviceId: string, position: ButtonPosition, pressType: ButtonPressType): Error | null;
 }