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

package/dist/model/device.d.ts

@@ -0,0 +1,265 @@
+/**
+ * The single, concrete {@link Device} class.
+ *
+ * There are **no subclasses**. A device's behaviour is entirely determined by its resolved
+ * `{ codec, capabilities, properties }` (see `resolveDevice`). Code asks
+ * `device.has("light")` / `device.getProperty("battery")` — never `instanceof FloodlightCamera`.
+ *
+ * Live state is held as a flat map of `PropertyValue`, updated by feeding raw param maps
+ * (from the cloud record or P2P notifications) into {@link Device.applyParams}. Params the model
+ * doesn't recognise are **not dropped** — they are kept as `unknown_<paramType>` passthrough, so
+ * coverage can grow later without losing data today (the graceful-unknown rule, applied to params).
+ *
+ * @module model/device
+ */
+import type { Capability, CloudRecord, CommandContext, PropertyChange, PropertySpec, PropertyValue, ResolvedDevice } from "./types.js";
+import type { CommandSink, MediaProvider, Ff09SettingsReader, RawDpCodec } from "../core/contracts.js";
+import { type Logger } from "../core/logger.js";
+import { type CapabilityAccessors, type DeviceManifest } from "./capabilities/index.js";
+/** Prefix used for params that have no `PropertySpec` mapping yet. */
+export declare const UNKNOWN_PARAM_PREFIX = "unknown_";
+/** A raw param map as delivered by the cloud / P2P: param_type → raw value. */
+export type RawParams = Record<number | string, string | number | boolean>;
+/**
+ * A eufy device: one class, capability-driven. Construct from a resolved record (or a raw
+ * `CloudRecord` via {@link Device.fromRecord}), then feed it param updates.
+ */
+export declare class Device {
+    /** Serial number (station/device SN). */
+    readonly sn: string;
+    /**
+     * The station this device's traffic belongs to: its parent HomeBase, or its own {@link sn} when it has none.
+     *
+     * Set from the record's `parentSn`, which is present only for a device that hangs off a base. A record that
+     * states none leaves the last known value, as every other identity field here does, so it starts at this
+     * device's own serial and every device therefore has a station.
+     */
+    stationSn: string;
+    /** Resolved command-codec family. */
+    codec: ResolvedDevice["codec"];
+    /** Resolved capability set. Widens if the device later reports evidence for more. */
+    capabilities: readonly Capability[];
+    /** Merged property schema (one entry per known property this device exposes). */
+    properties: readonly PropertySpec[];
+    /**
+     * What the user named this device in the app (`device_name`), falling back to {@link modelName} when
+     * the record carries none.
+     */
+    name: string;
+    /** Model / T-code from the record ("T8410"), when known. */
+    model?: string;
+    /** The model's display name ("Indoor Cam Pan & Tilt") — the product this unit is one of. */
+    modelName: string;
+    /** Which resolver tier produced the codec/caps. */
+    source: ResolvedDevice["source"];
+    /** Fast capability lookup. */
+    private capSet;
+    /** propertyName → spec, for applyParams. */
+    private specByName;
+    /**
+     * paramType → { spec, invert } for applyParams. Includes each spec's own `paramType` (invert
+     * from the spec) plus any `readAliases` (invert from the alias) so a property that rides
+     * different wire ids across device families still resolves to one named value.
+     */
+    private specByParam;
+    /** Which param namespace this device's ids live in (clean DPs vs security P2P). */
+    private namespace;
+    /** The record's `device_name` as stated, before the {@link modelName} fallback is applied. */
+    private deviceName?;
+    /** Live property values, keyed by property name (or `unknown_<pt>`). */
+    private readonly state;
+    /**
+     * Bound action objects per capability the device HAS, keyed by camelCased capability id
+     * (`light`, `ptz`, `camera`). Empty until {@link bindActions} runs — a bare model object
+     * (no network) has no actions. Populated by `EufyMega.getDevice`; surfaced through the fluent
+     * `dev.<cap>()` accessors ({@link CapabilityAccessors}).
+     */
+    private actionMap;
+    /**
+     * Whether {@link bindActions} has run — published through {@link describe} because an unbound device
+     * has no bound objects to enumerate, and "exposes nothing" and "not wired up yet" are different
+     * answers a caller has to be able to tell apart.
+     */
+    private bound;
+    /**
+     * Read-through freshness policy (injected by the facade via {@link setFreshnessPolicy}; the model
+     * stays transport-free — it only calls the supplied `refresh`). Default: caching OFF
+     * (`staleAfterMs = Infinity`), so a bare model object never triggers a fetch and existing behaviour
+     * is unchanged until the client wires a policy.
+     */
+    private staleAfterMs;
+    private refresher?;
+    /** Guards against firing more than one background refresh at a time (coalesces rapid stale reads). */
+    private refreshInFlight;
+    /**
+     * Host-supplied diagnostics sink. Defaults to {@link noopLogger} (silent) so a bare model object
+     * stays quiet; the facade passes its own `logger` through {@link fromRecord}. Used to WARN when a
+     * wire value doesn't match its declared `PropertySpec.type` (see {@link coerceByType}).
+     */
+    private readonly logger;
+    constructor(sn: string, resolved: ResolvedDevice, logger?: Logger);
+    /**
+     * Adopt a resolution: the capability set, the property schema, and everything derived from them.
+     *
+     * Shared by the constructor and {@link reresolve} so a widened device is indistinguishable from one
+     * that resolved that way to begin with — a second derivation path here would be a slow-drifting bug,
+     * since only the re-resolve case would exercise it.
+     */
+    private resolveInto;
+    /**
+     * Re-resolve against a fresher record and adopt the result if the capability set grew.
+     *
+     * A capability is granted on evidence the device reports, so a device that hadn't reported a param
+     * when it was first resolved lacks the capability that param proves — and would keep lacking it for
+     * the object's whole lifetime, even as the value itself started arriving. Re-resolving on fresh
+     * evidence closes that: the accessor appears, already bound if the device is bound.
+     *
+     * Only ever widens. A param the device stops reporting does not retract a capability, because the
+     * cloud record is a snapshot that can lose a field for reasons that have nothing to do with the
+     * hardware, and revoking an accessor a caller already holds is worse than keeping a quiet one.
+     *
+     * Returns the capabilities gained, empty when nothing changed — so a caller can skip re-binding.
+     */
+    reresolve(rec: CloudRecord): Capability[];
+    /**
+     * Wire this device to a {@link CommandSink} so its semantic action objects become live
+     * (`device.light?.on()`). `ctx` carries the evidence a capability uses to resolve the right
+     * command variant. Called by `EufyMega.getDevice`; a raw model object left unbound simply has
+     * no action objects (all accessors return `undefined`). `ff09Settings` reads that frame family's
+     * settings over whichever transport the device has; `rawDp` reads the structured payloads a few params
+     * carry in place of a scalar. Both are optional and both are named for the job, not the caller — a
+     * read needing one returns `undefined` without it. See `CapabilityModule.actions`'s doc before
+     * threading a third. The final `buildActions` arg is the live-state reader backing the capabilities' typed
+     * read getters (`dev.battery()?.level`): it closes over `this.getProperty`, so a getter built once
+     * here stays current as realtime/poll updates land in `this.state`.
+     */
+    bindActions(ctx: CommandContext, sink: CommandSink, media?: MediaProvider, ff09Settings?: Ff09SettingsReader, rawDp?: RawDpCodec): void;
+    /**
+     * Install the fluent capability accessors (`dev.ptz()`, `dev.light()`, …) once, for EVERY
+     * known accessor name — each reads `this.actionMap` live, so an accessor returns `undefined`
+     * (never "not a function") on an unbound device or one lacking the capability, and starts
+     * returning the action object after {@link bindActions}. Capability-agnostic: the names come
+     * from the barrel projection {@link accessorNamesFor}, so `device.ts` never names a
+     * capability. The single cast here is the only place the {@link CapabilityAccessors} types erase.
+     */
+    private installAccessors;
+    /** Build a Device from a raw cloud record (runs the 3-tier resolver). */
+    static fromRecord(sn: string, rec: CloudRecord, logger?: Logger): Device;
+    /**
+     * Take the unit's own identity — its name and model code — from the record.
+     *
+     * Separate from {@link resolveInto} because the resolver answers about the PRODUCT: it has no
+     * `device_name` to give, and re-running it must not replace "Dining room" with "Indoor Cam Pan &
+     * Tilt". Re-applied on every {@link reresolve} so a rename in the app lands on the next refresh.
+     *
+     * A record that omits a field is silent about it rather than asserting it went away — the same
+     * reasoning that keeps {@link reresolve} from retracting a capability — so an omission keeps the last
+     * known value and only a stated one replaces it.
+     */
+    private adoptIdentity;
+    /** Does this device have the given capability? */
+    has(cap: Capability): boolean;
+    /** Is the given property name part of this device's schema? */
+    hasProperty(name: string): boolean;
+    /**
+     * Wire a read-through freshness policy. When a cached property is older than `staleAfterMs`, a
+     * `getProperty`/`getProperties` read schedules ONE coalesced background `refresh()` (the facade
+     * supplies it, choosing the cheapest live transport) and returns the last-known value immediately —
+     * reads never block. Push / P2P realtime updates refresh `ts` themselves via {@link applyParams}, so
+     * a device kept fresh by realtime never re-fetches (a fresh entry is never stale). Keeps `model/`
+     * transport-free: the device only calls the injected callback.
+     */
+    setFreshnessPolicy(policy: {
+        staleAfterMs: number;
+        refresh: () => Promise<void>;
+    }): void;
+    /**
+     * Low-level property read by name — the untyped escape hatch. The typed fluent capability getters
+     * (`dev.battery()?.level`, `dev.contact()?.open`) answer the value already narrowed to its declared
+     * type where the property is exposed by a capability; this answers the loose `PropertyValue.value`
+     * (`boolean|number|string|object`). It is the only read for an unbound model object (no live client →
+     * no `dev.<cap>()`) and for a param not yet surfaced on a capability. Returns `undefined` if never
+     * observed.
+     */
+    getProperty(name: string): PropertyValue | undefined;
+    /**
+     * Snapshot of all current property values (named + unknown passthrough) — the untyped bulk read, for
+     * diagnostics / discovery. The typed fluent capability getters (`dev.battery()?.level`, …) answer one
+     * specific known property; this loose map answers every observed value at once. Under a freshness
+     * policy, schedules a background refresh when the OLDEST observed value is stale (one fetch covers
+     * every param) and returns the current snapshot immediately.
+     */
+    getProperties(): Record<string, PropertyValue>;
+    /**
+     * Fire the injected background refresh at most once at a time (coalescing rapid stale reads). The
+     * refresh calls {@link applyParams}, which updates each value's `ts` — so subsequent reads see fresh
+     * entries and stop re-triggering until the next staleness window. Fire-and-forget; never throws to
+     * the reader (a failed refresh just leaves the last-known value in place).
+     */
+    private scheduleRefresh;
+    /**
+     * Apply a raw param map (cloud record or P2P notification). Known params update their named
+     * property; unrecognised params are retained as `unknown_<paramType>` so nothing is lost.
+     *
+     * @param params param_type → raw value.
+     * @param ts observation time (epoch ms); defaults to `Date.now()`.
+     * @returns the list of property names whose value changed.
+     */
+    applyParams(params: RawParams, ts?: number): string[];
+    /**
+     * Which of these changed property names are worth ANNOUNCING, each with the value
+     * {@link getProperty} now serves for it — the second half of an {@link applyParams} call, and the input
+     * a facade turns into a property-change event.
+     *
+     * Only a name in this device's own schema survives, and EVERY name in it does. The schema is what the
+     * SDK published and {@link getProperty} serves every entry of, so announcing one is honest; a
+     * dictionary-named param and an `unknown_<paramType>` passthrough are things the SDK makes no claim
+     * about, and announcing either would promise a value it never agreed to serve. Diagnostics reach those
+     * through `inspectParams`.
+     *
+     * Nothing is withheld for being uninteresting, here or in a capability's own table. Which of a device's
+     * truths a host acts on is the host's call: a withheld value cannot be recovered, where an unwanted one
+     * costs a caller one comparison on the name.
+     *
+     * The value comes out of live state — written microseconds earlier by the same call that produced
+     * `changed` — through the same `narrow` the capability getters use, which is what makes an announcement
+     * and the getter beside it one answer rather than two. Not from the raw wire value: that is a second
+     * conversion and a second answer, which is exactly how a payload comes to disagree with its getter. And
+     * not by invoking the installed getter, which has read side effects (a scheduled background refresh, a
+     * codec call) an announcement must not trigger — and which an `unexposed` schema property does not have
+     * at all.
+     *
+     * Kept beside the state and the schema rather than in a caller, because both are here; a caller doing
+     * the join would be re-deriving what this object already holds. Says nothing about the previous value:
+     * a caller that needs the delta already holds it, because it was told last time.
+     */
+    announcements(changed: readonly string[]): PropertyChange[];
+    /**
+     * What this device exposes, as data — every installed read with what its value MEANS, every offerable
+     * action with what it accepts, and every event each capability emits.
+     *
+     * Beside {@link toJSON} rather than folded into it, because the two answer different questions and
+     * `toJSON` fires on every implicit `JSON.stringify` (an event payload, a log line) where the shape is
+     * not wanted. This one carries **shape only** — no values; read those through the capability getters
+     * it names.
+     *
+     * The reads and actions are the ones this device actually installed, so a caller can offer everything
+     * listed: a write the device gave no evidence for, or one whose wire is not confirmed, is absent
+     * rather than described. An unbound device (no live client) has nothing bound to enumerate and answers
+     * `bound: false` with empty `details`. `details` is resolved against this device's own facts (codec,
+     * model, capabilities), so a per-device enum domain (e.g. `workingMode`) carries the same options the
+     * property schema does.
+     */
+    describe(): DeviceManifest;
+    /** Plain-object view: serial, name, resolved codec/source, capabilities, and every current property value. */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Declaration merge: give {@link Device} the fluent capability accessors (`dev.ptz()`,
+ * `dev.light()`, `dev.camera()`, …) with full IDE typing, WITHOUT `device.ts` naming a single
+ * capability. The accessor names + return types come from {@link CapabilityAccessors} (a projection
+ * of the capability modules in the barrel); `bindActions` installs the matching closures at runtime.
+ * Adding a capability adds an accessor here automatically — no edit to this file.
+ */
+export interface Device extends CapabilityAccessors {
+}

package/dist/model/index.d.ts

@@ -1,7 +1,32 @@
 /**
- * Device domain: the `Device` record, its capabilities, classification, events and parameters.
+ * Device model — public barrel.
  *
- * Describes what a device MEANS, never how it is spoken to. It never imports `transport/` or a wire
- * library.
+ * Data-driven, capability-based device model: one {@link Device} class, behaviour resolved from
+ * a {@link CloudRecord} via the 3-tier {@link resolveDevice} (model row → codec → inference).
+ *
+ * @module model
+ */
+export * from "./types.js";
+export { classify, codecForType, codecFromModel } from "./classify.js";
+export { inferName } from "./infer.js";
+export { MODEL_REGISTRY, resolveDevice } from "./registry.js";
+export { Device, UNKNOWN_PARAM_PREFIX, type RawParams } from "./device.js";
+export { SECURITY_PARAMS, CLEAN_PARAMS, type ParamDef } from "./param-dictionary.js";
+export { LIFE_PARAMS } from "./life-params.js";
+export { parseCleanRecords, EMPTY_CLEAN_RECORD_PAGE, type CleanRecord, type CleanRecordPage } from "./clean-records.js";
+export { parseCleanRecordDetail, unwrapCleanRecordBlob, CLEAN_FINISH_REASONS, type CleanRecordDetail, type CleanFinishReason, } from "./clean-record-detail.js";
+export { decodeVacuumSchedules, decodeVacuumScheduleCount, decodeActiveVacuumScheduleCount, VACUUM_SCHEDULE_ACTIONS, VACUUM_SCHEDULE_WEEKDAYS, type VacuumSchedule, type VacuumScheduleAction, type VacuumScheduleWeekday, } from "./vacuum-schedules.js";
+export { decodeVacuumScenes, decodeVacuumSceneCount, decodeUsableVacuumSceneCount, SCENE_TYPES, SCENE_INVALID_REASONS, type VacuumScene, type SceneType, type SceneInvalidReason, } from "./vacuum-scenes.js";
+export { decodeVacuumMap, decodeVacuumMapGeometry, decodeVacuumMapBackup, decodeVacuumMapDescription, decodeVacuumPose, decodeVacuumRestrictedZones, decodeVacuumRoomOutline, decodeVacuumRoomParams, DOCK_KINDS, FLOOR_TYPES, MAP_CELL_VALUES, MAP_FRAME_KINDS, MAP_QUALITIES, ROOM_SCENES, ROOM_SUCTIONS, type DockKind, type FloorType, type MapCellValue, type MapDock, type MapFrameKind, type MapLine, type MapPoint, type MapPose, type MapQuad, type MapQuality, type RoomScene, type RoomSuction, type VacuumMapBackup, type VacuumMapDescription, type VacuumMapGeometry, type VacuumMapPlane, type VacuumRestrictedZones, type VacuumRoom, type VacuumRoomOutline, type VacuumRoomParams, type VacuumRoomSettings, } from "./vacuum-map.js";
+export { cellAtPoint, mapCellValue, mapCellValueAt, pointAtCell, roomAtPoint, roomIdAt, roomIdAtPoint, type MapCell, type PlacedPlane, } from "./map-pixels.js";
+export { VacuumMapStore, type VacuumMapPiece, type VacuumMapSnapshot } from "./vacuum-map-store.js";
+export { paramDef, namespaceForCodec, type ParamNamespace } from "./param-namespace.js";
+export { inspectParams, type ParamInspection, type DeviceInspection } from "./inspect.js";
+export * from "./capabilities/index.js";
+/**
+ * The evidence a family gate reads, published because a member table's `available` predicate names it —
+ * `AUDIO_MEMBERS.alarmTone` gates on being a HomeBase, and that gate's parameter type is this. The
+ * DeviceType sets and the predicates themselves stay internal to `device-family.ts`.
  */
-export {};
+export type { FamilyContext } from "./device-family.js";
+export { CusPushEvent, CusPushAlarmType, CusPushMode, DoorbellPushEvent, IndoorPushEvent, HB3PairedDevicePushEvent, LockPushEvent, SmartDropPushEvent, NotificationStyle, detectionName, } from "./push-events.js";

package/dist/model/infer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Naming inference.
+ *
+ * Capability *detection* (evidence params, model/category hints, vendor device-type tables) lives
+ * per-capability in `src/model/capabilities/*` (each module's `detection` spec) and is dispatched by
+ * the barrel's `detectCapabilities`. What lives here is the one piece that is about *naming*, not
+ * capabilities: {@link inferName}.
+ *
+ * @module model/infer
+ */
+import type { CloudRecord } from "./types.js";
+/**
+ * Best-effort display name from a cloud record. Prefers a clean uppercase model T-code
+ * (e.g. `"T8423"`); falls back to `undefined`. Never throws.
+ *
+ * A "clean model code" is the eufy product-code shape: a leading letter (usually `T`) plus
+ * digits, optionally with a short alphanumeric suffix. We normalise case and trim noise; if
+ * the model doesn't look like a code at all we return `undefined` rather than echoing junk.
+ *
+ * @param rec The cloud device record.
+ * @returns The normalised model code, or `undefined` when none is usable.
+ */
+export declare function inferName(rec: CloudRecord): string | undefined;

package/dist/model/inspect.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Device inspection — turn a real device's reported params into an enrichment report.
+ *
+ * Given a cloud record (model/deviceType/params), this produces:
+ *  - the resolved `{ codec, capabilities, name }`,
+ *  - a per-param table cross-referenced against the param dictionary (known/unknown, name,
+ *    provenance, inferred type, live value),
+ *  - a **paste-ready `registry.ts` row** for the device's model, and
+ *  - **paste-ready param-dictionary snippets** for every param we don't yet know.
+ *
+ * Pure + offline (no network) so it is unit-testable; the live wrapper that fetches a device by
+ * serial lives on `EufyMega.inspectDevice`.
+ *
+ * @module model/inspect
+ */
+import type { CloudRecord, PropertySource, PropertyValueType, RegistryEntry, ResolvedDevice } from "./types.js";
+import { type ParamNamespace } from "./param-namespace.js";
+/** One reported param, cross-referenced against our dictionary. */
+export interface ParamInspection {
+    paramType: number;
+    /** Raw reported value (as delivered). */
+    value: string;
+    /** True when the param is in our dictionary for this namespace. */
+    known: boolean;
+    /** Our dictionary name, or `param<pt>` when unknown. */
+    name: string;
+    /** Trust of the dictionary mapping (absent ⇒ not in dictionary). */
+    provenance?: PropertySource;
+    /** Type inferred from the live value (bool/number/string). */
+    inferredType: PropertyValueType;
+}
+/** Full inspection report for one device. */
+export interface DeviceInspection {
+    sn?: string;
+    model?: string;
+    deviceType?: number;
+    namespace: ParamNamespace;
+    resolved: ResolvedDevice;
+    params: ParamInspection[];
+    counts: {
+        total: number;
+        known: number;
+        unknown: number;
+        unconfirmed: number;
+    };
+    /** Suggested curated registry row (codec + extra caps + name). */
+    suggestedRegistry: {
+        model: string;
+        entry: RegistryEntry;
+        exists: boolean;
+    };
+    /** Paste-ready `registry.ts` line. */
+    registrySnippet: string;
+    /** Paste-ready param-dictionary lines for the unknown params. */
+    dictionarySnippet: string;
+}
+/**
+ * Inspect a cloud device record and produce the enrichment report. `rec.params` should be the
+ * device's reported `param_type → value` map (e.g. from the device list / get_device_param_list).
+ */
+export declare function inspectParams(rec: CloudRecord, sn?: string): DeviceInspection;

package/dist/model/life-params.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `eufy_life` DP param space — the tag ids a T8L0x smart light reports on its own realtime wire.
+ *
+ * These are **DP tag numbers, not cloud param ids**, and they live in their own namespace because the
+ * numbers collide: tag `0xa3` = 163 means strip length here and battery level in the vacuum DP space.
+ * The read-side meanings are also unrelated to the write-side tags that share the same numbers on the
+ * outbound leg (`0xa1` is a timestamp there, power here) — device→app and app→device are two separate
+ * mappings over one tag range.
+ *
+ * CONFIRMED two ways (2026-07-28): decoded live off a real T8L02's status reports, matching the app's
+ * own `deviceInfoPayloadDataParse` transcription field for field. Each entry's DP tag and the app's
+ * field name for it are noted beside it.
+ *
+ * Names match the `PropertySpec.name`s in `capabilities/smart-light.ts` so a value resolves to the same
+ * property whether it arrives through this dictionary or the capability's own spec table.
+ *
+ * @module model/life-params
+ */
+import type { ParamDef } from "./param-dictionary.js";
+/** Tag ids a `eufy_life` light reports. Only fields whose meaning is evidenced appear here. */
+export declare const LIFE_PARAMS: Record<number, ParamDef>;

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

@@ -0,0 +1,70 @@
+import type { MapCellValue, MapPoint, VacuumMapPlane, VacuumRoom, VacuumRoomOutline, VacuumRoomParams } from "./vacuum-map.js";
+/** A cell's position in a plane, counting from the plane's own origin corner. */
+export interface MapCell {
+    readonly col: number;
+    readonly row: number;
+}
+/**
+ * What both planes have in common: a grid of a known size, anchored somewhere in the world.
+ *
+ * `VacuumMapGeometry` and `VacuumRoomOutline` both satisfy this, which is what lets one set of
+ * conversions serve both without either knowing about the other.
+ */
+export interface PlacedPlane {
+    readonly width: number;
+    readonly height: number;
+    /** Centimetres per cell. `undefined` when the device omitted it, and then nothing here can convert. */
+    readonly resolution: number | undefined;
+    /** Where cell `(0, 0)` is anchored, in centimetres. */
+    readonly origin: MapPoint;
+}
+/**
+ * Which cell covers a world position, or `undefined` when the position falls outside the plane.
+ *
+ * Both axes count UP: a larger `y` is a larger `row`. The vendor's own renderer flips the image
+ * vertically before drawing it, which is a display choice and not a property of the data — reading the
+ * flip back into the coordinates would put every lookup in the wrong half of the map.
+ *
+ * `undefined` also when the plane has no `resolution`, because there is then no scale to divide by and
+ * a guessed one silently misplaces every lookup.
+ */
+export declare function cellAtPoint(plane: PlacedPlane, point: MapPoint): MapCell | undefined;
+/**
+ * Where a cell sits in the world, in centimetres — the inverse of {@link cellAtPoint}.
+ *
+ * The point returned is what the cell is anchored at, and `cellAtPoint` rounds to the nearest cell, so
+ * the two round-trip. `undefined` for a cell outside the plane or a plane with no resolution.
+ */
+export declare function pointAtCell(plane: PlacedPlane, cell: MapCell): MapPoint | undefined;
+/**
+ * What one cell of the map is — floor, wall, carpet or unexplored.
+ *
+ * The plane packs four cells to a 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`.
+ * `undefined` for a cell outside the map.
+ */
+export declare function mapCellValue(map: VacuumMapPlane, cell: MapCell): MapCellValue | undefined;
+/** What the map says about a world position. */
+export declare function mapCellValueAt(map: VacuumMapPlane, point: MapPoint): MapCellValue | undefined;
+/**
+ * Which room a cell of the ROOM OUTLINE belongs to, or `undefined` where none does.
+ *
+ * That plane is one byte per cell, and the byte is not the room id on its own: its low two bits carry
+ * a sub-type and the id is what remains above them. A reader taking the whole byte reports room 4 as
+ * room 19 and finds no such room in the list.
+ *
+ * A resulting id of `0` reads as `undefined`. Unmapped space and the gaps between rooms carry zero, and
+ * there is no room 0 to look up — reporting it as an id would have a caller searching the room list for
+ * something that was never in it.
+ */
+export declare function roomIdAt(outline: VacuumRoomOutline, cell: MapCell): number | undefined;
+/** Which room covers a world position. */
+export declare function roomIdAtPoint(outline: VacuumRoomOutline, point: MapPoint): number | undefined;
+/**
+ * The room at a world position, named — the join of the outline's room id with the room list.
+ *
+ * Takes the outline and the room list separately because the device sends them separately, on two
+ * channels that arrive at different times: a caller holding one without the other gets `undefined`
+ * rather than a wrong answer.
+ */
+export declare function roomAtPoint(outline: VacuumRoomOutline, rooms: VacuumRoomParams, point: MapPoint): VacuumRoom | undefined;

package/dist/model/param-dictionary.d.ts

@@ -0,0 +1,28 @@
+/**
+ * AUTHORITATIVE param dictionary — the app's own decompiled constant names joined with a live
+ * param-sweep of real owned devices.
+ *
+ * Two namespaces (params are per-transport, NOT globally unique):
+ *  - SECURITY_PARAMS — eufy P2P param space (ids 1000+). **Membership is the observation**: an id is
+ *    listed only because the sweep saw it on a real owned device, so the id is real/accepted.
+ *    `provenance` is the trust of the NAME/meaning: "verified" (our captures) > "apk" (the app's own
+ *    decompiled constant name) > "guessed" (no name source — needs toggle-diff).
+ *  - CLEAN_PARAMS — RoboVac Tuya DP space (ids 1 and above), names from the cloud
+ *    `get_product_data_point` data_point_list (provenance "mega" — authoritative).
+ *
+ * Which models reported an id, and the capture that named it, are in the commit that adds the entry.
+ */
+import type { PropertyValueType, PropertySource, ParamEncoding } from "./types.js";
+/** One param definition in the dictionary. */
+export interface ParamDef {
+    /** Stable camelCase code-facing name. */
+    name: string;
+    type: PropertyValueType;
+    provenance: PropertySource;
+    /** How the wire value is encoded, when not a plain scalar (decode on read, encode on write). */
+    encoding?: ParamEncoding;
+}
+/** eufy P2P security param space (ids 1000+). */
+export declare const SECURITY_PARAMS: Record<number, ParamDef>;
+/** RoboVac Tuya DP space (ids ~150-180), from get_product_data_point. */
+export declare const CLEAN_PARAMS: Record<number, ParamDef>;

package/dist/model/param-namespace.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Param namespaces — which id space a device's reported `paramType`s live in.
+ *
+ * The three spaces overlap numerically and mean unrelated things, so a lookup MUST be namespaced: id
+ * `163` is `battery` as a vacuum Tuya DP and `lightLength` as a `eufy_life` DP tag. Resolving a param
+ * without its namespace is how one product line's state silently reads as another's.
+ *
+ * This lives outside `param-dictionary.ts` so the namespace union and the dispatch stay one small table
+ * a reader can hold at once, next to the guard that a codec resolves to exactly one namespace — rather
+ * than at the head of two thousand entries.
+ *
+ * @module model/param-namespace
+ */
+import type { Codec } from "./types.js";
+import { type ParamDef } from "./param-dictionary.js";
+/** The param id spaces this SDK models. */
+export type ParamNamespace = "security" | "clean" | "life" | "print";
+/** Look up a param def in the given namespace. */
+export declare function paramDef(ns: ParamNamespace, paramType: number): ParamDef | undefined;
+/** The param namespace a device's ids live in, from its codec, via the module-local `NAMESPACE_BY_CODEC` table. */
+export declare function namespaceForCodec(codec: Codec): ParamNamespace;

package/dist/model/proto-read.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The field readers every Raw-DP decoder on this line shares.
+ *
+ * `RawDpCodec` hands back a flat list of `{ field, kind, value }` and stops there — it has no schema
+ * and no idea which message it just walked. Turning that list into a reading is the decoder's job, and
+ * these are the readers every decoder on this line shares: the interesting part is not the code but the
+ * RULE each one encodes, and a rule spelled out in three places drifts in two of them.
+ *
+ * **The rule, in one line: proto3 omits a zero, so absent and zero are the same bytes.** A field set to
+ * `0`, `false` or `""` is not written to the wire at all, which means no reader here can tell "the
+ * device said zero" from "the device said nothing". Every function below therefore answers with the
+ * zero member rather than with `undefined`, and a decoder that needs the distinction has to find it
+ * somewhere else in the message — a `oneof` branch, a sibling flag, a wrapper message whose presence
+ * is itself the signal. Reading a defaulted zero as a real value is where this project's silent wire
+ * bugs have come from, three times over.
+ *
+ * @module model/proto-read
+ */
+import type { RawDpCodec, RawDpField } from "../core/contracts.js";
+/** Read a varint field as a number, or `0` — proto3 omits a zero, so absent and zero are one value. */
+export declare function int(fields: readonly RawDpField[] | undefined, field: number): number;
+/** Read a bool field on the same terms: absent is `false`, because that is what the vendor omitted. */
+export declare function flag(fields: readonly RawDpField[] | undefined, field: number): boolean;
+/**
+ * Read a `sint32`/`sint64` field, undoing the zig-zag encoding.
+ *
+ * The codec reads every varint unsigned, because the wire does not say which of `int32`, `sint32` and
+ * `uint32` a field was declared as — only the message's author knows, and that is the decoder. A
+ * `sint32` maps small negatives onto small unsigned values so they cost one byte instead of ten, and
+ * left alone they read as large positives: the map's coordinates are signed centimetres and routinely
+ * negative, so a point at `-150` would otherwise decode to `299` and place a wall on the wrong side of
+ * the room. This is the exact inverse of the writer's `zigzag`.
+ */
+export declare function signed(fields: readonly RawDpField[] | undefined, field: number): number;
+/**
+ * Read a string field, or `undefined`.
+ *
+ * An empty string reads as `undefined` too: proto3 omits it, so a device that sent no name and one
+ * that sent an empty name are the same bytes, and `""` is not a name.
+ */
+export declare function text(fields: readonly RawDpField[] | undefined, field: number): string | undefined;
+/**
+ * Read a length-delimited field as its raw bytes — a blob the sender did not intend as a message.
+ *
+ * Distinct from {@link sub} on purpose: a pixel plane and a nested message are the same wire type, and
+ * asking for one when the payload holds the other is how a decoder ends up walking image data as if it
+ * were fields. An empty payload reads as `undefined`, on the same proto3 rule as {@link text}.
+ */
+export declare function bytes(fields: readonly RawDpField[] | undefined, field: number): Buffer | undefined;
+/** Step into a sub-message, or `undefined` when the container is absent or is not one. */
+export declare function sub(codec: RawDpCodec, fields: readonly RawDpField[] | undefined, field: number): readonly RawDpField[] | undefined;
+/** Every repeat of one length-delimited field, stepped into — `find` would collapse a repeated one. */
+export declare function each(codec: RawDpCodec, fields: readonly RawDpField[] | undefined, field: number): (readonly RawDpField[])[];