@mega-yfue/eufy-sdk 0.0.4 → 0.1.0-beta.0

package/dist/model/vacuum-map.d.ts

@@ -0,0 +1,286 @@
+/**
+ * The robot's map, as `stream.proto` describes it — the messages that arrive on the `biz/…/res` leg.
+ *
+ * Six message types carry everything about a map: its size and where it sits in
+ * the world, which cell is floor and which is wall, which room each cell belongs to, what those rooms
+ * are called and how they are cleaned, and where the user drew a line the robot must not cross. This
+ * decodes all six. It does not draw anything: what it hands back is dimensions, coordinates, names and
+ * two pixel planes.
+ *
+ * **Units, once, because every coordinate here shares them.** Distances are centimetres — the vendor
+ * writes them as "m × 100" throughout — and `resolution` is the width of one cell in those same
+ * centimetres, so a cell at `(col, row)` covers world position `origin + (col, row) × resolution`. An
+ * angle is radians × 100. Nothing is converted on the way through: a value the device sent as an
+ * integer stays one, because dividing it here would make every caller guess whether it had been.
+ *
+ * **What is deliberately not read.** `RestrictedZone.suggestion` carries zones the robot has *proposed*
+ * and the user has not accepted. Merging them into the real lists would report restrictions the robot
+ * is not enforcing, and reporting them as fact is worse than not reporting them at all.
+ *
+ * @module model/vacuum-map
+ */
+import type { RawDpCodec } from "../core/contracts.js";
+import type { CleanExtent, MopLevel, VacuumCleanType } from "./capabilities/vacuum-clean.js";
+/** A position on the map, in centimetres from the map's own origin. */
+export interface MapPoint {
+    readonly x: number;
+    readonly y: number;
+}
+/** A position with a heading. `theta` is radians × 100, as the device sends it. */
+export interface MapPose extends MapPoint {
+    readonly theta: number;
+}
+/** A virtual wall: the segment between two points that the robot will not cross. */
+export interface MapLine {
+    readonly from: MapPoint;
+    readonly to: MapPoint;
+}
+/**
+ * A four-cornered zone, corners in the order the device sent them.
+ *
+ * Not necessarily a rectangle — the vendor's type is `Quadrangle`, and the app lets a zone be rotated
+ * — so the corners describe a polygon and not a bounding box.
+ */
+export interface MapQuad {
+    readonly corners: readonly [MapPoint, MapPoint, MapPoint, MapPoint];
+}
+/** What a dock is: a bare charging base, or a full station with water and dust handling. */
+export declare const DOCK_KINDS: readonly ["charger", "station"];
+export type DockKind = (typeof DOCK_KINDS)[number];
+/** Where a dock stands, and which kind it is. */
+export interface MapDock {
+    readonly kind: DockKind;
+    readonly pose: MapPose;
+}
+/**
+ * How complete the device considers this map.
+ *
+ * `"listFull"` is not a quality at all but a notice: the robot has nowhere left to store a new map and
+ * is telling the app to replace one or discard this. It shares the field, so it is named here.
+ */
+export declare const MAP_QUALITIES: readonly ["incomplete", "rough", "effective", "listFull"];
+export type MapQuality = (typeof MAP_QUALITIES)[number];
+/** Size, placement and quality of a map — the vendor's `MapInfo`. */
+export interface VacuumMapGeometry {
+    /** Cells across and down. Both are non-zero: a plane without dimensions cannot be indexed. */
+    readonly width: number;
+    readonly height: number;
+    /**
+     * The width of one cell in centimetres, or `undefined` when the device omitted it.
+     *
+     * No default is invented for the absent case. The reference integration substitutes 5 without saying
+     * why, and a guessed scale silently misplaces every zone and every room label on the map.
+     */
+    readonly resolution: number | undefined;
+    /** Where cell `(0, 0)` sits, in centimetres. Signed, and routinely negative. */
+    readonly origin: MapPoint;
+    /** Clockwise rotation the app applies when drawing, in degrees. */
+    readonly angle: number;
+    readonly quality: MapQuality;
+    /** Every dock the device knows about. Empty until the robot has seen one. */
+    readonly docks: readonly MapDock[];
+}
+/** Whether a map frame replaces what came before it, or amends it. */
+export declare const MAP_FRAME_KINDS: readonly ["full", "incremental"];
+export type MapFrameKind = (typeof MAP_FRAME_KINDS)[number];
+/**
+ * What one cell of {@link VacuumMapPlane.cells} means, by its two-bit value.
+ *
+ * Indexed by the value itself, so `MAP_CELL_VALUES[2]` is `"free"`.
+ */
+export declare const MAP_CELL_VALUES: readonly ["unknown", "obstacle", "free", "carpet"];
+export type MapCellValue = (typeof MAP_CELL_VALUES)[number];
+/** A map frame — the vendor's `Map`, with its pixel plane decompressed. */
+export interface VacuumMapPlane {
+    /**
+     * Whether this frame is the whole map or an amendment to the last one.
+     *
+     * **How an `"incremental"` frame is applied is not known.** Nothing states whether it replaces a
+     * region, carries its own origin, or assumes the previous frame's geometry. A stale-but-correct map
+     * beats one assembled by a guessed rule.
+     */
+    readonly frame: MapFrameKind;
+    /** The device's id for this map. `undefined` when it sent none. */
+    readonly mapId: number | undefined;
+    /** The map's name, as the user set it. `undefined` when unnamed. */
+    readonly name: string | undefined;
+    /** The map's revision counter. It advances whenever the map is edited. */
+    readonly releases: number;
+    /** The frame's position in a sequence, as the device counts it. Zero on a lone frame. */
+    readonly index: number;
+    readonly geometry: VacuumMapGeometry;
+    /**
+     * The cell plane, decompressed: **four cells per byte, two bits each, low bits first**, in one run
+     * with no row padding. The cell at `(col, row)` is at bit `(i & 3) * 2` of byte `i >> 2`, where
+     * `i = row * width + col`, and its value indexes {@link MAP_CELL_VALUES}.
+     *
+     * Handed over packed rather than expanded. A large map is a megabyte once every cell is its own
+     * byte.
+     */
+    readonly cells: Buffer;
+}
+/** Which room each cell belongs to — the vendor's `RoomOutline`, with its plane decompressed. */
+export interface VacuumRoomOutline {
+    readonly mapId: number | undefined;
+    readonly releases: number;
+    readonly width: number;
+    readonly height: number;
+    readonly resolution: number | undefined;
+    /**
+     * Where this plane's cell `(0, 0)` sits, in centimetres.
+     *
+     * **Its own origin, not the map's.** The two planes are not guaranteed to start at the same world
+     * position, so a room lookup under a map cell must convert through world coordinates rather than
+     * reusing the index.
+     */
+    readonly origin: MapPoint;
+    /**
+     * The room plane: **one byte per cell**, `row * width + col`, no padding — a different packing from
+     * {@link VacuumMapPlane.cells}, which the vendor states separately for each.
+     *
+     * The byte is not the room id on its own. Its low two bits carry a sub-type and the id is the
+     * remaining bits, so the room at a cell is `cells[i] >> 2`.
+     */
+    readonly cells: Buffer;
+}
+/** What kind of floor a room has, by the vendor's `Floor.Type`. */
+export declare const FLOOR_TYPES: readonly ["unknown", "carpet", "wood", "tile"];
+export type FloorType = (typeof FLOOR_TYPES)[number];
+/** What kind of room this is, by the vendor's `RoomScene.Type`. */
+export declare const ROOM_SCENES: readonly ["unknown", "study", "bedroom", "bathroom", "kitchen", "livingRoom", "diningRoom", "corridor"];
+export type RoomScene = (typeof ROOM_SCENES)[number];
+/**
+ * Suction, on the scale the vendor declares for a room's `Fan.suction`.
+ *
+ * **Not the `SuctionLevel` scale DP 158 uses, and the two must not be unified.** DP 158 reports suction on a six-value
+ * scale where 4 is BoostIQ and 5 is Max Pro; `clean_param.proto` declares this field's enum with five
+ * values ending at `MAX_PLUS = 4`. They agree from 0 to 3 and disagree at 4, so naming a room's
+ * `Fan.suction` through the DP scale would report "BoostIQ" for a room the user set to Max+.
+ *
+ * A live capture showed DP 158 and `clean_param.fan` moving together, which is why the clean-parameter
+ * read treats them as one scale — but that capture only covered 0 and 2, where both scales agree. The
+ * divergence above is declared by the vendor, not contradicted by anything observed, so this follows
+ * the proto the field is actually declared in.
+ */
+export declare const ROOM_SUCTIONS: readonly ["quiet", "standard", "turbo", "max", "maxPlus"];
+export type RoomSuction = (typeof ROOM_SUCTIONS)[number];
+/** The per-room clean settings, when the user has set any. */
+export interface VacuumRoomSettings {
+    readonly cleanType: VacuumCleanType | undefined;
+    readonly suction: RoomSuction | undefined;
+    readonly mopLevel: MopLevel | undefined;
+    readonly cleanExtent: CleanExtent | undefined;
+    /** How many passes this room gets. `undefined` for the vendor's zero, which means "not set". */
+    readonly cleanTimes: number | undefined;
+}
+/** One room on the map. */
+export interface VacuumRoom {
+    /** The room's id — what the byte in {@link VacuumRoomOutline.cells} resolves to, and what a room-select frame names. */
+    readonly id: number;
+    /**
+     * The name the user gave this room, or `undefined`.
+     *
+     * `undefined` is common and is not a decode failure: the vendor's own comment says an unnamed room
+     * is labelled by the app from {@link VacuumRoom.scene} and {@link VacuumRoom.sceneIndex} — "Kitchen 1",
+     * "Bedroom 2" — in the user's language. A host wanting the same label builds it the same way, which
+     * it can only do if the absence is reported rather than papered over.
+     */
+    readonly name: string | undefined;
+    readonly scene: RoomScene;
+    /** Which room of its kind this is, counting from 1. Pairs with {@link VacuumRoom.scene} to name it. */
+    readonly sceneIndex: number;
+    readonly floor: FloorType;
+    /** Where the room sits in the order the app lists them. */
+    readonly order: number;
+    /** This room's own clean settings. Only in force while {@link VacuumRoomParams.customEnabled}. */
+    readonly settings: VacuumRoomSettings;
+}
+/** The room list for a map — the vendor's `RoomParams`. */
+export interface VacuumRoomParams {
+    readonly mapId: number | undefined;
+    readonly releases: number;
+    /**
+     * Whether the per-room settings are in force.
+     *
+     * When `false` the device cleans every room with the global parameters and each room's
+     * {@link VacuumRoom.settings} is inert. The settings are still reported, because they are what the
+     * user last chose and what turning this on would restore.
+     */
+    readonly customEnabled: boolean;
+    /** The device's "smart mode" switch, which it reports alongside the rooms. */
+    readonly smartMode: boolean;
+    readonly rooms: readonly VacuumRoom[];
+}
+/** Everywhere the user has told the robot not to go — the vendor's `RestrictedZone`. */
+export interface VacuumRestrictedZones {
+    readonly mapId: number | undefined;
+    readonly releases: number;
+    /** Lines the robot will not cross. */
+    readonly virtualWalls: readonly MapLine[];
+    /** Areas the robot will not enter at all. */
+    readonly noGoZones: readonly MapQuad[];
+    /** Areas the robot may sweep but will not mop. */
+    readonly noMopZones: readonly MapQuad[];
+}
+/** A map's identity, without its pixels — the vendor's `MapDescription`. */
+export interface VacuumMapDescription {
+    readonly mapId: number | undefined;
+    readonly releases: number;
+    readonly name: string | undefined;
+    /**
+     * Why the map exists, as the device's own code. Not translated to names: the vendor ships this as a
+     * bare `uint32` with no enum beside it, so any name here would be invented.
+     */
+    readonly createCause: number;
+    /**
+     * When the map was made, and when it was last used, as the device sent them.
+     *
+     * **The unit is not stated.** The field is a `uint64` and could be seconds or milliseconds; both are
+     * used elsewhere on this line. A consumer can tell them apart by magnitude far more safely than this
+     * decoder can assume one. `undefined` for the vendor's zero, which is "never".
+     */
+    readonly createdAt: number | undefined;
+    /** See {@link VacuumMapDescription.createdAt}. */
+    readonly lastUsedAt: number | undefined;
+}
+/**
+ * A whole map in one message — the vendor's `MapBackup`, sent when a map is switched or edited.
+ *
+ * Every part is optional because the device sends what changed. A backup with only `description` set
+ * is a rename, and reading its absent `map` as an empty one would erase a map already held.
+ */
+export interface VacuumMapBackup {
+    readonly description: VacuumMapDescription | undefined;
+    readonly map: VacuumMapPlane | undefined;
+    readonly outline: VacuumRoomOutline | undefined;
+    readonly rooms: VacuumRoomParams | undefined;
+    readonly zones: VacuumRestrictedZones | undefined;
+}
+/** Decode a `MapInfo` message — size, placement and docks, with no pixels attached. */
+export declare function decodeVacuumMapGeometry(raw: unknown, codec: RawDpCodec | undefined): VacuumMapGeometry | undefined;
+/** Decode a `DynamicData` message — where the robot is, right now. */
+export declare function decodeVacuumPose(raw: unknown, codec: RawDpCodec | undefined): MapPose | undefined;
+/**
+ * Decode a `Map` message — a frame of the cell plane with the geometry that places it.
+ *
+ * `undefined` when the frame cannot be used rather than when it cannot be parsed: no geometry, no
+ * pixels, a plane that failed to decompress, or one too short for the grid it claims. Each of those
+ * yields a map that would draw, and draw wrongly.
+ */
+export declare function decodeVacuumMap(raw: unknown, codec: RawDpCodec | undefined): VacuumMapPlane | undefined;
+/** Decode a `RoomOutline` message — one byte per cell saying which room it belongs to. */
+export declare function decodeVacuumRoomOutline(raw: unknown, codec: RawDpCodec | undefined): VacuumRoomOutline | undefined;
+/** Decode a `RoomParams` message — the room list, their names, and how each is cleaned. */
+export declare function decodeVacuumRoomParams(raw: unknown, codec: RawDpCodec | undefined): VacuumRoomParams | undefined;
+/** Decode a `RestrictedZone` message — virtual walls, no-go zones and no-mop zones. */
+export declare function decodeVacuumRestrictedZones(raw: unknown, codec: RawDpCodec | undefined): VacuumRestrictedZones | undefined;
+/** Decode a `MapDescription` message — a map's identity, without its pixels. */
+export declare function decodeVacuumMapDescription(raw: unknown, codec: RawDpCodec | undefined): VacuumMapDescription | undefined;
+/**
+ * Decode a `MapBackup` message — the five-part snapshot sent when a map is switched or edited.
+ *
+ * Each part is decoded from its own bytes through the same decoder that reads it standing alone, so a
+ * backup and a live frame cannot drift apart. A part the device did not send stays `undefined` rather
+ * than becoming an empty one: an absent `map` in a rename is not a map with no cells.
+ */
+export declare function decodeVacuumMapBackup(raw: unknown, codec: RawDpCodec | undefined): VacuumMapBackup | undefined;

package/dist/model/vacuum-scenes.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The cleaning scenes a robot holds — `SceneResponse` on DP 180, decoded.
+ *
+ * A scene is a saved routine: which rooms or zones, in what order, with which clean parameters. The
+ * robot reports the LIST over this DP — ids, names, the map each belongs to, whether each still works
+ * — while the tasks inside a scene are only ever sent, never reported. So this reads what the device
+ * publishes and does not pretend to the rest.
+ *
+ * **A real `mapId` is on this DP.** Multi-map management on DP 172 cannot supply one:
+ * `multi_maps.proto` states outright that a `MAP_GET_ALL` or `MAP_GET_ONE` response travels over p2p
+ * rather than the data point, leaving DP 172 carrying only the method, sequence and result of an
+ * operation. `SceneInfo.mapid` is on the DP, and so is a scheduled rooms-clean's `map_id` — two reads
+ * that carry the id the area-select frames need, with no p2p transfer and no default invented for them.
+ *
+ * @module model/vacuum-scenes
+ */
+import type { RawDpCodec } from "../core/contracts.js";
+/**
+ * Why the device considers a scene unusable. `"none"` is the healthy case — the vendor's `NORMAL`,
+ * which every working scene reports.
+ *
+ * `"legacyDefault"` is the vendor's own dead value: its comment retires `DEFAULT = 5` in favour of the
+ * `type` field, so a device still sending it is naming a default scene the old way. Kept named rather
+ * than dropped, because a value that arrives and has no name reads as a decode failure.
+ */
+export declare const SCENE_INVALID_REASONS: readonly ["none", "mapMissing", "mapUnavailable", "mapMismatch", "other", "legacyDefault"];
+export type SceneInvalidReason = (typeof SCENE_INVALID_REASONS)[number];
+/** The vendor's four built-in scenes, and `"custom"` for one a user made. */
+export declare const SCENE_TYPES: readonly ["custom", "wholeHouseDaily", "wholeHouseDeep", "afterDinner", "petArea"];
+export type SceneType = (typeof SCENE_TYPES)[number];
+/** One saved scene, as the robot reports it. */
+export interface VacuumScene {
+    /** The device's own id for this scene — what `encodeSceneClean` takes to run it. */
+    readonly id: number;
+    /** The scene's name. `undefined` when the device sent none, which a built-in scene does. */
+    readonly name: string | undefined;
+    /** Whether the scene can still run. A scene whose map was deleted is kept and reported invalid. */
+    readonly valid: boolean;
+    /** Why it cannot run. `"none"` while {@link valid} — the vendor reports both fields either way. */
+    readonly invalidReason: SceneInvalidReason | undefined;
+    /**
+     * The map this scene's rooms belong to, and one of the two real map ids the device reports — the
+     * other being a scheduled rooms-clean's.
+     *
+     * `undefined` when the device sends its no-map sentinel, which is `-2` written into a `uint32`, and
+     * `undefined` for a zero as well: proto3 omits a zero-valued field, so a scene tied to map 0 and one
+     * that said nothing about a map are the same bytes. Reporting "no map" for both is the reading that
+     * cannot send a clean at the wrong floor.
+     */
+    readonly mapId: number | undefined;
+    /**
+     * How long the device expects a run to take, as it reports it. `undefined` for the vendor's `0`,
+     * which its own comment marks invalid rather than instant.
+     *
+     * **The unit is not stated anywhere.** Every other duration on this line is seconds, which is a
+     * reason to expect seconds and not a reason for this SDK to claim it — so the number is reported as
+     * sent and named for what it is.
+     */
+    readonly estimatedRuntime: number | undefined;
+    /** Where the scene sits in the list the app shows, counting from 1. */
+    readonly order: number;
+    /** Whether this is one of the vendor's built-in scenes, and which. */
+    readonly type: SceneType;
+}
+/**
+ * Decode a `SceneResponse` (DP 180) to the scenes it reports, or `undefined`.
+ *
+ * `undefined` means the payload could not be read — no codec, not a Raw-DP value, malformed bytes. An
+ * **empty array** is a different answer: the device reports its scenes in full on boot and after any
+ * change, so a report carrying none says this robot has no scenes saved.
+ */
+export declare function decodeVacuumScenes(raw: unknown, codec: RawDpCodec | undefined): readonly VacuumScene[] | undefined;
+/** How many scenes the robot holds, or `undefined` when the payload could not be read. */
+export declare function decodeVacuumSceneCount(raw: unknown, codec: RawDpCodec | undefined): number | undefined;
+/** How many of the reported scenes can still run. */
+export declare function decodeUsableVacuumSceneCount(raw: unknown, codec: RawDpCodec | undefined): number | undefined;

package/dist/model/vacuum-schedules.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The schedules a robot vacuum holds — `TimerResponse` on DP 164, decoded.
+ *
+ * The DP number comes from a `get_product_data_point` dump; the product catalogue names the DP, and the
+ * vendor's `timing.proto` carries the message.
+ *
+ * The shape is deeper than anything else on this line — a repeated `TimerInfo`, each with four nested
+ * containers and a `oneof` for what the timer actually does — which is why it decodes here rather than
+ * as one more field reader inside `vacuum-clean`. It reads a payload and answers a list; it never asks
+ * the device for one, and it holds no DP number of its own.
+ *
+ * **`TimerInfo.Addition` is deliberately not decoded.** It carries the account ids of whoever created
+ * and last edited each timer — the kind of value this SDK does not surface without a reason.
+ *
+ * @module model/vacuum-schedules
+ */
+import type { RawDpCodec } from "../core/contracts.js";
+/** What a timer runs when it fires, as the vendor's `Action` oneof names it. */
+export declare const VACUUM_SCHEDULE_ACTIONS: readonly ["autoClean", "roomsClean", "cruise", "sceneClean"];
+export type VacuumScheduleAction = (typeof VACUUM_SCHEDULE_ACTIONS)[number];
+/**
+ * Weekdays in the vendor's own bit order — Sunday first, because `Cycle.week_bits` puts it at bit 0.
+ *
+ * Written out rather than derived from a locale so the mapping is the wire's and not the reader's.
+ */
+export declare const VACUUM_SCHEDULE_WEEKDAYS: readonly ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
+export type VacuumScheduleWeekday = (typeof VACUUM_SCHEDULE_WEEKDAYS)[number];
+/** One schedule the robot holds. */
+export interface VacuumSchedule {
+    /** The device's own id for this timer — what a future edit or delete would name it by. */
+    readonly id: number;
+    /** Whether the timer is switched on. A valid timer that is off stays stored and does not fire. */
+    readonly enabled: boolean;
+    /**
+     * Whether the device still considers the timer usable. A timer pointing at a deleted scene or a map
+     * that no longer exists is reported `valid: false` rather than removed, so the app can show why.
+     */
+    readonly valid: boolean;
+    /** `true` for a weekly timer, `false` for one that fires once. */
+    readonly repeats: boolean;
+    /** Hour of the day it fires, 0–23, in the user's own timezone — see {@link utcOffsetSeconds}. */
+    readonly hour: number;
+    /** Minute of the hour it fires, 0–59. */
+    readonly minute: number;
+    /**
+     * The days a repeating timer fires on. Empty for a one-shot timer, and empty for a repeating one
+     * whose `week_bits` is zero — which the device treats as a timer that never fires.
+     */
+    readonly weekdays: readonly VacuumScheduleWeekday[];
+    /**
+     * The offset from UTC the timer's clock was set against, in seconds east.
+     *
+     * Carried per timer rather than per device: the robot stores whatever the phone that created the
+     * schedule told it, so an absolute instant follows from this offset and not from any local zone.
+     */
+    readonly utcOffsetSeconds: number;
+    /** Whether the phone that created the timer said its region observes daylight saving. */
+    readonly daylightSaving: boolean;
+    /** What the timer runs. */
+    readonly action: VacuumScheduleAction;
+    /** The map the run targets, for a rooms-clean or a cruise. */
+    readonly mapId?: number;
+    /** The rooms a rooms-clean visits, in the order the timer lists them. */
+    readonly roomIds?: readonly number[];
+    /** The scene a scene-clean runs. */
+    readonly sceneId?: number;
+    /** The scene's name as the device last saw it — kept so a deleted scene can still be named. */
+    readonly sceneName?: string;
+}
+/**
+ * Decode a `TimerResponse` (DP 164) to the schedules it reports, or `undefined`.
+ *
+ * `undefined` means the payload could not be read at all — no codec, not a Raw-DP value, malformed
+ * bytes. An **empty array** is a different and equally real answer: the device reports its timers in
+ * full every time, so a report carrying none says this robot has no schedules set.
+ *
+ * The device sends this unprompted on boot and after any change, and in reply to an `INQUIRY`. Which
+ * of those produced a given payload does not change the reading — every report is the complete list —
+ * so the request `method` and `seq` beside it are not surfaced.
+ */
+export declare function decodeVacuumSchedules(raw: unknown, codec: RawDpCodec | undefined): readonly VacuumSchedule[] | undefined;
+/** How many schedules a `TimerResponse` reports, or `undefined` when the payload could not be read. */
+export declare function decodeVacuumScheduleCount(raw: unknown, codec: RawDpCodec | undefined): number | undefined;
+/** How many of the reported schedules are switched on and still usable. */
+export declare function decodeActiveVacuumScheduleCount(raw: unknown, codec: RawDpCodec | undefined): number | undefined;

package/dist/transport/dp-preset.d.ts

@@ -0,0 +1,102 @@
+/**
+ * `0x020D` light-effect payload serializer for the `eufy_life` smart-light line: the catalog effect
+ * definition ({@link DpPresetSpec}) → the command-specific DP fields, including the per-layer
+ * header/colour/trailer encoding and the RGBCW colour approximation.
+ *
+ * Lives at the transport root, not under one transport folder, because two consumers need it and they
+ * sit in different subfolders: `mqtt/command-router.ts` serializes an effect to send it, and
+ * `http/light-catalog.ts` trial-serializes one to report whether the catalog entry is drivable at all.
+ * Same reason `ff09.ts` sits here. It builds FIELDS, not a frame — the DP framing + envelope stay in
+ * `mqtt/dp-codec.ts`, and nothing here names a capability or a transport.
+ *
+ * Header + trailer are byte-exact vs. real captures; colours run through {@link rgbcwBlock}, a
+ * physically-grounded approximation of the device's on-device 5-channel (R,G,B,WarmWhite,ColdWhite)
+ * mixing engine — EXACT on pure red and blue, ~18/255 mean on mixed colours, because the engine's
+ * nonlinear gamut expansion isn't fully reversed.
+ */
+import type { DpField } from "./mqtt/dp-codec.js";
+/** One layer of a gallery light effect, as the cloud catalog `params.layer[]` describes it. */
+export interface DpPresetLayer {
+    current_layer_type: number;
+    colors?: string;
+    layer_priority?: number;
+    layer_speed?: number;
+    layer_range?: number | [number, number];
+    interval_type?: number;
+    interval_value?: number;
+    layer_execution_parameter?: number;
+    light_effect_post_cycle_status?: number;
+    color_pick_mode?: number;
+    gradient_value?: number;
+    flow_direction?: number;
+    direction_change_mode?: number;
+    length_range?: number;
+    color_fill_mode?: number;
+    insert_block_mode?: number;
+    insert_block_range?: number | [number, number];
+    insert_black_block_mode?: number;
+    insert_black_block_range?: number | [number, number];
+    brightness_variation_type?: number;
+    brightness_range?: number | [number, number];
+    light_effect_cycle_method?: number;
+    execution_parameter?: number;
+    is_lights_move_with_people?: number;
+    brightness_value?: number;
+    display_mode?: number;
+    color_quantity_range?: number;
+    transition_mode?: number;
+    unit_transition_duration?: number;
+    color_switch_mode?: number;
+    switch_count?: number;
+    color_pick_sequence?: number;
+    blink_cycle_count?: number;
+    blink_position_mode?: number;
+    blink_interval?: number | [number, number];
+    blink_quantity?: number;
+    blink_asynchrony?: number;
+    blink_color_switch_mode?: number;
+}
+/** A resolved gallery effect, produced by the client (from the HTTP catalog) and serialized here. */
+export interface DpPresetSpec {
+    lightId: number;
+    speed: number;
+    layerExecutionMode: number;
+    layers: DpPresetLayer[];
+    /** The catalog's own overall brightness (0-100), sent as a companion `0x0201` frame. */
+    brightness?: number;
+}
+/** "RRGGBB" → the 5-byte wire block `[R,G,B,WarmWhite,ColdWhite]` via the RGBCW approximation. */
+export declare function rgbcwBlock(hex: string): Buffer | null;
+/**
+ * A single scalar byte. THROWS on an array: several catalog fields are scalar in the shapes the
+ * reverse-engineering validated, but some nature/moods effects carry a `[min,max]` pair in one of
+ * these slots (e.g. `interval_value: [1,1]`), and how the app packs that into the fixed-width header
+ * is NOT reversed. Silently collapsing the pair to a byte would ship a mis-packed frame that the light
+ * ignores while the fire-and-forget write reports success — worse than failing. Refuse it, exactly as
+ * {@link layerTrailer} bails on an unknown layer type, until a capture pins the packing down.
+ */
+export declare const b8: (v: unknown) => number;
+/**
+ * Whether {@link dpPresetFields} would succeed on this spec, decided WITHOUT building the frame.
+ * An effect is drivable only if it has at least one layer, every top-level scalar fits a byte, and
+ * every layer has a known `current_layer_type`, byte-sized fields, and RGB-hex colours — the same set
+ * {@link dpPresetFields} accepts, checked field-for-field.
+ *
+ * Deliberately does not call {@link layerBlob}: a trial build runs {@link rgbcwBlock}'s gamut search
+ * per colour and allocates a buffer per layer, and the catalogue runs this over every entry of a
+ * many-hundred-id scan. `layerHeader`/`layerTrailer` raise every relevant throw on plain numbers, and
+ * a colour only has to satisfy the same hex test `rgbcwBlock` gates on.
+ */
+export declare function specIsSerializable(spec: {
+    speed?: unknown;
+    layerExecutionMode?: unknown;
+    layers: readonly DpPresetLayer[];
+}): boolean;
+/**
+ * Build the `0x020D` light-effect frame's command-specific fields (`0xa3` onward — the header
+ * `a3`-`a8` plus one `0xa9+idx` layer blob each). `a1`/`a2` are prepended by {@link buildDpFrame}.
+ * `a7` is deliberately absent (an empty slot in every real capture).
+ */
+export declare function dpPresetFields(spec: DpPresetSpec): DpField[];
+/** The `0xa4`-brightness `0x0201` device-info fields for the companion brightness write. */
+export declare function dpLevelFields(level: number): DpField[];