/**
 * Utilities to help decode packets from the UniFi Protect realtime events API.
 *
 * UniFi OS update events data packets are used to provide a realtime stream of updates to Protect. It differs from the system events API in that the system events API
 * appears to be shared across other applications (Network, Access, etc.) while the updates events API appears to only be utilized by Protect and not shared by other
 * applications, although the protocol is shared.
 *
 * So how does it all work? Cameras continuously stream updates to the UniFi Protect controller containing things like camera health, statistics, and, crucially for us,
 * events such as motion and doorbell ring. A complete update packet is composed of four frames:
 *
 * ```
 * ----------------
 * | Header Frame | (8 bytes)
 * ----------------
 * | Action Frame |
 * ----------------
 * | Header Frame | (8 bytes)
 * ----------------
 * | Data Frame   |
 * ----------------
 * ```
 *
 * The header frame is required overhead since websockets provide only a transport medium. It's purpose is to tell us what's coming in the frame that follows.
 *
 * The action frame identifies what the action and category that the update contains:
 *
 * | Property    | Description                                                                      |
 * |-------------|----------------------------------------------------------------------------------|
 * | action      | What action is being taken. Known actions are `add` and `update`.                |
 * | id          | The identifier for the device we're updating.                                    |
 * | modelKey    | The device model category that we're updating.                                   |
 * | newUpdateId | A new UUID generated on a per-update basis. This can be safely ignored it seems. |
 *
 * The final part of the update packet is the data frame. The data frame can be three different types of data - although in practice, I've only seen JSONs come across.
 * Those types are:
 *
 * | Payload Type |                                                 Description                                                |
 * |--------------|------------------------------------------------------------------------------------------------------------|
 * | 1            | JSON. For update actions that are not events, this is always a subset of the configuration bootstrap JSON. |
 * | 2            | A UTF8-encoded string                                                                                      |
 * | 3            | Node Buffer                                                                                                |
 *
 * Some tips:
 *
 * - `update` actions are always tied to the following modelKeys: camera, event, nvr, and user.
 *
 * - `add` actions are always tied to the `event` modelKey and indicate the beginning of an event item in the Protect events list. A subsequent `update` action is sent
 *   signaling the end of the event capture, and it's confidence score for motion detection.
 *
 * - The above is NOT the same thing as motion detection. If you want to detect motion, you should watch the `update` action for `camera` modelKeys, and look for a JSON
 *   that updates lastMotion. For doorbell rings, lastRing. The Protect events list is useful for the Protect app, but it's of limited utility to HomeKit, and it's slow
 *   = relative to looking for lastMotion that is. If you want true realtime updates, you want to look at the `update` action.
 *
 * - JSONs are only payload type that seems to be sent, although the protocol is designed to accept all three.
 *
 * - With the exception of update actions with a modelKey of event, JSONs are always a subset of the bootstrap JSON, indexed off of modelKey. So for a modelKey of camera,
 *   the data payload is always a subset of {@link ProtectTypes.ProtectCameraConfigInterface | ProtectCameraConfigInterface}.
 *
 * @module ProtectApiEvents
 */
import { Nullable } from "./protect-types.js";
import { ProtectLogging } from "./protect-logging.js";
/**
 * UniFi Protect event packet.
 *
 * @param header   - Protect event header.
 * @param payload  - Protect event payload.
 *
 * @remarks A UniFi Protect event packet represents a realtime event update from a UniFi Protect controller. There are two components to each packet, a `header` and
 *   a `payload`. The `header` contains information about which Protect device and what action category it belongs to. The `payload` contains the detailed information
 *   related to the device and action specified in the header.
 */
export type ProtectEventPacket = {
    header: ProtectEventHeader;
    payload: unknown;
};
/**
 * UniFi Protect event header.
 *
 * @param header   - Protect event header.
 * @param payload  - Protect event payload.
 *
 * @remarks A UniFi Protect event packet represents a realtime event update from a UniFi Protect controller. There are two components to each packet, a `header` and
 *   a `payload`. The `header` contains information about which Protect device and what action category it belongs to and can contain arbitrary information, though has
 *   a few properties that are always present (`action`, `id`, `modelKey`, and `newUpdateId`). The `payload` contains the detailed information related to the device and
 *   action specified in the header.
 */
export type ProtectEventHeader = {
    action: string;
    id: string;
    modelKey: string;
    newUpdateId: string;
    [key: string]: boolean | number | object | string;
};
/**
 * UniFi Protect event utility class that provides functions for decoding realtime event API packet frames.
 */
export declare class ProtectApiEvents {
    /** @internal */
    constructor();
    /**
     * Decode a UniFi Protect event packet.
     *
     * @param log     - Logging functions to use.
     * @param packet  - Input packet to decode.
     *
     * @remarks A UniFi Protect event packet is an encoded representation of state updates that occur in a UniFi Protect controller. This utility function takes an
     * encoded packet as an input, and decodes it into an event header and payload that can be acted upon. An example of it's use is in {@link ProtectApi} where, once
     * successfully logged into the Protect controller, events are generated automatically and can be accessed by listening to `message` events emitted by
     * {@link ProtectApi}.
     */
    static decodePacket(log: ProtectLogging, packet: Buffer): Nullable<ProtectEventPacket>;
    private static decodeFrame;
}