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

package/dist/model/push-events.d.ts

@@ -0,0 +1,147 @@
+/**
+ * eufy push-notification constants.
+ *
+ * PROVENANCE: the event-type codes are cross-checked against the v6 APK
+ * (com.oceanwing.battery.cam) — the AI-detection codes are present in the v6
+ * runtime, and v6 uses the same Firebase project (batterycam-3250a / sender
+ * 348804314802), so this set is current. v6-only additions noted inline.
+ *
+ * These are the push-event SEMANTICS the capability layer matches on (motion/doorbell/person/…);
+ * {@link detectionName} maps a code to a human label. Pure MCS wire framing is a transport concern
+ * and lives with the transport, not here.
+ */
+/** Generic custom push event (field `a` in CusPushData). */
+export declare enum CusPushEvent {
+    SECURITY = 1,
+    TFCARD = 2,
+    DOOR_SENSOR = 3,
+    CAM_STATE = 4,
+    GSENSOR = 5,
+    BATTERY_LOW = 6,
+    BATTERY_HOT = 7,
+    LIGHT_STATE = 8,
+    MODE_SWITCH = 9,
+    ALARM = 10,
+    BATTERY_FULL = 11,
+    REPEATER_RSSI_WEAK = 12,
+    UPGRADE_STATUS = 13,
+    MOTION_SENSOR_PIR = 14,
+    ALARM_DELAY = 16,
+    HUB_BATT_POWERED = 17,
+    SENSOR_NO_OPEN = 18,
+    SMART_DROP = 20
+}
+/** Alarm trigger source. */
+export declare enum CusPushAlarmType {
+    HUB_STOP = 0,
+    DEV_STOP = 1,
+    GSENSOR = 2,
+    PIR = 3,
+    APP = 4,
+    HOT = 5,
+    DOOR = 6,
+    CAMERA = 7,
+    MOTION_SENSOR = 8,
+    CAMERA_GSENSOR = 9,
+    CAMERA_APP = 10,
+    CAMERA_LINKAGE = 11,
+    HUB_LINKAGE = 12,
+    HUB_KEYPAD_PANIC_BUTTON = 13,
+    HUB_KEYPAD_EMERGENCY_CODE = 14,
+    HUB_STOP_BY_KEYPAD = 15,
+    HUB_STOP_BY_APP = 16,
+    HUB_STOP_BY_HUB = 17,
+    HUB_KEYPAD_CUSTOM_NOT_MAP = 18
+}
+/** Arming/mode-switch source. */
+export declare enum CusPushMode {
+    SWITCH_FROM_KEYPAD = 1,
+    SWITCH_FROM_APP = 2,
+    SWITCH = 9
+}
+/** Doorbell AI-detection events (3xxx). All v6-confirmed. */
+export declare enum DoorbellPushEvent {
+    BACKGROUND_ACTIVE = 3100,
+    MOTION_DETECTION = 3101,
+    FACE_DETECTION = 3102,
+    PRESS_DOORBELL = 3103,
+    PET_DETECTION = 3106,
+    VEHICLE_DETECTION = 3107,
+    PACKAGE_DELIVERED = 3301,
+    PACKAGE_TAKEN = 3302,
+    FAMILY_DETECTION = 3303,
+    PACKAGE_STRANDED = 3304,
+    SOMEONE_LOITERING = 3305,
+    RADAR_MOTION_DETECTION = 3306,
+    AWAY_FROM_HOME = 3307,
+    RADAR_DETECTION = 3308
+}
+/** Indoor-camera AI-detection events. */
+export declare enum IndoorPushEvent {
+    MOTION_DETECTION = 3101,
+    FACE_DETECTION = 3102,
+    CRYING_DETECTION = 3104,
+    SOUND_DETECTION = 3105,
+    PET_DETECTION = 3106,
+    VEHICLE_DETECTION = 3107
+}
+/** HomeBase-3 paired-device AI-detection events (3108-3112 are v6-era). */
+export declare enum HB3PairedDevicePushEvent {
+    MOTION_DETECTION = 3101,
+    FACE_DETECTION = 3102,
+    PRESS_DOORBELL = 3103,
+    CRYING_DETECTION = 3104,
+    SOUND_DETECTION = 3105,
+    PET_DETECTION = 3106,
+    VEHICLE_DETECTION = 3107,
+    DOG_DETECTION = 3108,
+    DOG_LICK_DETECTION = 3109,
+    DOG_POOP_DETECTION = 3110,
+    IDENTITY_PERSON_DETECTION = 3111,
+    STRANGER_PERSON_DETECTION = 3112
+}
+/** Lock action / status events. */
+export declare enum LockPushEvent {
+    MANUAL_UNLOCK = 257,
+    AUTO_UNLOCK = 258,
+    PW_UNLOCK = 259,
+    FINGERPRINT_UNLOCK = 260,
+    APP_UNLOCK = 261,
+    MANUAL_LOCK = 262,
+    KEYPAD_LOCK = 263,
+    APP_LOCK = 264,
+    AUTO_LOCK = 265,
+    PW_LOCK = 266,
+    FINGER_LOCK = 267,
+    TEMPORARY_PW_LOCK = 268,
+    TEMPORARY_PW_UNLOCK = 269,
+    LOW_POWER = 513,
+    VERY_LOW_POWER = 514,
+    MULTIPLE_ERRORS = 515,
+    LOCK_OFFLINE = 516,
+    MECHANICAL_ANOMALY = 517,
+    VIOLENT_DESTRUCTION = 518,
+    LOCK_MECHANICAL_ANOMALY = 519,
+    DOOR_OPEN_LEFT = 520,
+    DOOR_TAMPER = 521,
+    DOOR_STATE_ERROR = 522,
+    STATUS_CHANGE = 769,
+    OTA_STATUS = 770,
+    LOCK_ONLINE = 771
+}
+/** SmartDrop locker events. */
+export declare enum SmartDropPushEvent {
+    LOW_BATTERY = 6,
+    OVERHEATING_WARNING = 7,
+    TAMPERED_WARNING = 10,
+    BATTERY_FULLY_CHARGED = 11,
+    PERSON_DETECTED = 3102
+}
+/** Push notification presentation style. */
+export declare enum NotificationStyle {
+    TEXT = 1,
+    THUMB = 2,
+    ALL = 3
+}
+/** Resolve a 3xxx AI-detection event id to a human name (camera/doorbell). */
+export declare function detectionName(eventType: number): string;

package/dist/model/registry.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Device registry + the **3-tier resolver**.
+ *
+ * Resolving a {@link CloudRecord} to a {@link ResolvedDevice} (`{ codec, capabilities,
+ * properties, name }`) is the heart of the data-driven model. Most-specific wins, but the
+ * result is always *additive* so nothing is ever lost:
+ *
+ *  1. **model row** (curated, tier 1) — a hand-authored {@link RegistryEntry} keyed by T-code.
+ *     Best naming + curated extra capabilities. Optional; most devices never need one.
+ *  2. **category default** (tier 2) — {@link classify} maps the cloud `device_type` (or, failing
+ *     that, the model code) to a {@link Codec}, which contributes its baseline capabilities.
+ *  3. **inference** (tier 3) — {@link detectCapabilities} adds whatever the device can *prove*
+ *     about itself from its reported params + model/category strings (graceful unknown).
+ *
+ * The final capability set is the union of all three tiers (deduped), minus the ones a module marks
+ * {@link import("./capabilities/types").CapabilityModule.ownedByStation} when the record says this
+ * device hangs off a parent — the one place the result is subtractive, because a control the group's
+ * owner holds is one this device cannot answer for however it was granted. `source` records the most
+ * authoritative tier that fired, for diagnostics.
+ *
+ * The curated rows below are intentionally a **small seed** — the system classifies and works
+ * read-only for devices with no row at all. Rows exist only to add curation (pretty names,
+ * capabilities not provable from params alone). They are the place to encode model-specific
+ * knowledge as it is *confirmed* (via the APK / a mega query) — never as a dumping ground.
+ *
+ * @module model/registry
+ */
+import type { CloudRecord, RegistryEntry, ResolvedDevice, Capability, Codec, PropertySpec } from "./types.js";
+/**
+ * Curated model rows (tier 1), keyed by **uppercase T-code**. Seed set only — extend as model
+ * specifics are confirmed. Capabilities here are *added* to the codec baseline + inference.
+ *
+ * NOTE: these are illustrative seeds chosen to exercise the resolver; each should be confirmed
+ * against first-party evidence before being relied on (same trust rule as param ids).
+ */
+export declare const MODEL_REGISTRY: Readonly<Record<string, RegistryEntry>>;
+/**
+ * Resolve a cloud device record into its full model shape via the 3-tier lookup.
+ *
+ * Capability precedence (earlier = wins on property-name conflicts in `mergeProperties`):
+ * curated row caps → codec baseline → inferred extras.
+ *
+ * @param rec the minimal cloud record (deviceType / model / category / params).
+ * @returns the resolved `{ codec, capabilities, properties, name, source }`.
+ */
+export declare function resolveDevice(rec: CloudRecord): ResolvedDevice;
+/**
+ * The property manifest for a device, from its capabilities and the record's facts. The single place
+ * an {@link AvailabilityContext} is built — so a family-gate (`available`) and a per-model enum
+ * (`enumValuesFor`) are decided from the same truthful, session-free view on every path (initial
+ * resolve and {@link Device.reresolve}). Populated only from what a record carries, never transport
+ * fields a live session hasn't produced.
+ */
+export declare function resolveProperties(rec: CloudRecord, codec: Codec, capabilities: Capability[]): PropertySpec[];

package/dist/model/types.d.ts

@@ -0,0 +1,301 @@
+/**
+ * Device model — shared contract.
+ *
+ * The whole model is **data-driven and capability-based**.
+ * There is exactly ONE concrete device class; behaviour comes from:
+ *
+ *  - a **codec** (axis B2 — how commands are framed/routed for a device *family*), and
+ *  - a set of composable **capabilities** (axis A — what the device exposes), each of which
+ *    contributes a property schema (and, later, command behaviour).
+ *
+ * A device's `{ codec, capabilities }` is resolved by a 3-tier lookup
+ * (exact model row → category default → inference). New SKUs in a known family need no code.
+ *
+ * This file is the integration contract: every other `src/model/*` module imports from here.
+ */
+/**
+ * Command-codec families (axis B2). One per genuinely-different wire protocol.
+ *
+ * `station|camera|sensor|lock|keypad` are the eufy **security** families (P2P; param space
+ * 1000+). `vacuum` is the eufy **clean** line (RoboVac) — a different transport (Tuya/MQTT
+ * data-points) and a different param namespace (DP ids ~150-180), so its params come from a
+ * separate authoritative source (`get_product_data_point` → `data_point_list`), NOT the P2P
+ * device list. Per-namespace param dictionaries, not one global table.
+ *
+ * `light` is the eufy **life** smart-lighting line (e.g. T8L02 "Permanent Outdoor Lights") — its
+ * own secure-MQTT "DP" TLV wire, decoded by its own transport codec. Named distinctly
+ * from the camera-floodlight `light` *capability* so the two never collide as bare `"light"`.
+ *
+ * `display` is the T87Ax Smart Display line — its own codec because its `device_type` collides with
+ * the security residual range (confirmed live, 2026-09-04: it connects over secure MQTT with no
+ * `p2p_did`, never P2P). Its param namespace and product line are nonetheless grouped into `security`
+ * by maintainer decision, not wire evidence — see {@link namespaceForCodec}. No capability module
+ * targets it yet: no screen/audio/assistant param has been observed, only its own small cloud-param
+ * namespace (ids 8001-8006).
+ */
+export type Codec = "station" | "camera" | "sensor" | "lock" | "keypad" | "vacuum" | "mower" | "light" | "printer" | "display";
+/**
+ * Capability identifiers (axis A). A capability is a composable feature a device exposes;
+ * it maps to a {@link CapabilityModule} that owns its property schema. Extend this union as
+ * new capabilities are modelled — adding one never requires a subclass.
+ */
+export type Capability = "video" | "snapshot" | "motion" | "person_detection" | "battery" | "light" | "ptz" | "doorbell" | "contact" | "leak" | "smoke" | "co" | "siren" | "lock" | "keypad" | "arming" | "storage" | "rtsp" | "camera" | "audio" | "vacuum_clean" | "vacuum_dock" | "suction" | "locate" | "smart_light" | "info";
+/** Value type of a property. */
+export type PropertyValueType = "bool" | "number" | "string" | "enum";
+/**
+ * What a value MEANS, as opposed to how it is stored — the semantic annotation that makes a reading
+ * convertible without a hardcoded table per property.
+ *
+ * `PropertyValueType` says a value is a number; this says whether that number is a battery
+ * percentage, a temperature, a signal strength, a duration or an instant. The distinction is not
+ * cosmetic: a `seconds` duration and a `timestamp` instant are both numbers of seconds, and treating
+ * one as the other is wrong in a way no type check catches.
+ *
+ *  - `boolean` — an on/off state (always paired with `type: "bool"`).
+ *  - `percent` / `celsius` / `dbm` / `seconds` / `hours` / `megabytes` / `degrees` — a measured quantity
+ *    in the unit the device reports it in; each pairs with the matching `unit`. Values are
+ *    never converted on the way out — a converted reading is an invented one. `seconds` and `hours`
+ *    are separate kinds for exactly that reason: a robot reports a run in seconds and a consumable's
+ *    wear in hours, and normalising one into the other would publish a number the device never sent.
+ *  - `scalar` — a plain number in no unit at all: a step on a ladder, a mode index, a raw level, a
+ *    segment count. Ordered and comparable, but its range and direction are the device's, so nothing
+ *    but the device says what a given value means.
+ *  - `bitfield` — a number whose individual bits carry the meaning, not its magnitude.
+ *  - `enum` — one of a named set; the set is the property's `enumValues` (raw → label) or, for a value
+ *    a read decodes, the read's own `values`.
+ *  - `identifier` — an opaque id whose domain lives elsewhere (a cloud-fetched list), so it is not
+ *    ordered and not arithmetic.
+ *  - `timestamp` — an instant, unix seconds.
+ *  - `text` — free-form or structured text with no further promise.
+ *
+ * Three pairs are close enough to pick wrongly, so the test for each:
+ *
+ *  - **`scalar` vs a measured quantity** — is there a unit the device reports it in? A sensitivity
+ *    step, a mode index and a segment count are all `scalar` precisely because there is none; they
+ *    are NOT counts of anything, and the name says only "a bare number". A quantity with a unit takes
+ *    the kind naming that unit, and the two are checked against each other in both directions.
+ *  - **`identifier` vs `enum`** — can we publish the set? An `enum` ships its options with it, so its
+ *    label needs nothing else. An `identifier` is a number whose domain is
+ *    held somewhere we do not control (a catalogue the app fetches), so there is no set to ship and
+ *    arithmetic on it — ordering, nearest-value, a range — is meaningless.
+ *  - **`bitfield` vs `enum`** — one value, or several at once? A bitfield's bits combine, so it has no
+ *    single label and its magnitude means nothing. The named bits belong to the capability that
+ *    decodes them and are exported beside that decoder; unlike an enum's options they are not carried
+ *    here, which is a gap this vocabulary does not close on its own.
+ */
+export declare const KNOWN_VALUE_KINDS: readonly ["boolean", "percent", "celsius", "dbm", "seconds", "hours", "megabytes", "degrees", "scalar", "bitfield", "enum", "identifier", "timestamp", "text"];
+/** One of the kinds this version models — the closed half of {@link ValueKind}. */
+export type KnownValueKind = (typeof KNOWN_VALUE_KINDS)[number];
+/**
+ * A value kind — {@link KnownValueKind}, left **open** on purpose.
+ *
+ * Adding a member to a closed union is a breaking change for every caller with an exhaustive switch;
+ * adding one to the open form is not. A caller maps the kinds it knows and falls through to a default
+ * for the rest, so a newly-modelled kind degrades to "shown raw" instead of failing to compile.
+ */
+export type ValueKind = KnownValueKind | (string & {});
+/**
+ * Whether a kind is one this version models, narrowing it to {@link KnownValueKind}.
+ *
+ * The counterpart to leaving the union open: the compiler cannot tell a caller that a kind is one it
+ * has a branch for, because at a declaration site any string is accepted. This is how a caller writes
+ * the fallback branch the open union asks for — and, in the other direction, how the SDK's own specs
+ * catch a kind that was typed rather than modelled.
+ */
+export declare function isKnownValueKind(kind: ValueKind): kind is KnownValueKind;
+/**
+ * Trust provenance of a property's `param_type` mapping, most-trusted first:
+ *  - `mega`     — confirmed against the live mega API / a real device's reported params.
+ *  - `apk`      — extracted from the v6 app itself (the ids the app actually sends — authoritative).
+ *  - `verified` — confirmed by our own capture/observation.
+ *  - `guessed`  — a plausible placeholder; lowest trust.
+ *
+ * This project never relies on a third-party reverse-engineering project as a source of trust —
+ * every id/behavior we ship is grounded in the app's
+ * own decompiled code (`apk`) or our own capture/observation (`verified`), never someone else's
+ * unverified guess. Absent provenance is treated as `guessed`.
+ *
+ * Provenance of a property definition — an internal trust label used when curating the model.
+ * @internal
+ */
+export type PropertySource = "mega" | "apk" | "verified" | "guessed";
+/**
+ * A single device property, mapped to its P2P `param_type`. This is pure data — the same
+ * spec is reused across every device whose capability contributes it.
+ */
+export interface PropertySpec {
+    /** Stable, code-facing name (e.g. "battery", "light", "motionDetection"). */
+    name: string;
+    /** The eufy P2P `param_type` carrying this value (the wire id). */
+    paramType: number;
+    type: PropertyValueType;
+    /** Human unit, when meaningful (e.g. "%", "°C", "dBm"). */
+    unit?: string;
+    /**
+     * What the value means ({@link ValueKind}) — the machine-readable half of {@link unit}.
+     *
+     * Absent when the stored value carries no scalar meaning of its own: a structured payload whose
+     * semantic value is a field inside it declares the kind on the member that decodes it
+     * instead, since that is where the meaning becomes true.
+     */
+    kind?: ValueKind;
+    /** Whether the value can be written back to the device (a setter exists). */
+    writable: boolean;
+    /** Allowed values for `type: "enum"` (raw → label). */
+    enumValues?: Record<number, string>;
+    /**
+     * Trust level of this `paramType` mapping. Default (absent) = `guessed`. Anything still `guessed`
+     * is a candidate for confirmation against a first-party source, never relied on.
+     */
+    provenance?: PropertySource;
+    /**
+     * Wire polarity for a `bool` property whose param is a *disable* flag: when `true`, a raw
+     * `0`/`false` means the property is TRUE (e.g. a camera's `enabled` — the flag is the
+     * disable bit, so `"0"` ⇒ enabled). Ignored for non-bool types.
+     */
+    invert?: boolean;
+    /**
+     * Custom decode for a value the wire delivers as a code the app *reinterprets* — a bitfield/enum
+     * that means something other than its face value. Given the raw param value, returns the decoded
+     * property value. When present it REPLACES the default type-coercion (and `invert`). Example: the
+     * battery `charging` flag is derived from the reported charge status, matching the app's
+     * own Hermes decode — see `capabilities/battery.ts`.
+     */
+    decode?: (raw: string | number | boolean) => boolean | number | string;
+    /**
+     * This param carries a STRUCTURED PAYLOAD rather than a scalar — a base64 protobuf that the
+     * capability's own getter reads a field out of, with the injected codec in scope.
+     *
+     * The stored value is that payload verbatim, and {@link type} describes what the getter ANSWERS
+     * rather than what arrives on the wire. Those are different for every Raw DP on the clean line: nine
+     * consumable counters are `"number"` over one base64 string, and reading the value as a number is
+     * exactly what must NOT happen at ingest.
+     *
+     * Storage already keeps such a value intact — a non-numeric string cannot be coerced to a number, so
+     * it is passed through. What this flag changes is that the pass-through stops being reported as a
+     * mistake: a robot reporting ten Raw DPs on every push logged ten warnings a time saying its
+     * properties were misdeclared, which is how a real warning goes unread.
+     */
+    raw?: true;
+    /**
+     * Extra wire param ids that ALSO carry this property on some device families, with their own
+     * polarity. The device's own `paramType` wins; otherwise the first alias the device reports wins.
+     * Lets one property (e.g. `enabled`) read correctly across families that report it under
+     * different ids (a battery camera and a standalone one disagree) — the family variance lives
+     * in the capability spec, not in per-device branches.
+     */
+    readAliases?: ReadonlyArray<{
+        paramType: number;
+        invert?: boolean;
+    }>;
+    /** Short description for docs / discovery. */
+    description?: string;
+}
+/**
+ * A decoded property value. Most params are scalar, but some carry a structured payload that the
+ * device delivers **encoded** (base64-wrapped JSON, or a JSON string) — e.g. motion-detection
+ * zones, privacy zones, guard-mode configs. Those are decoded to the object/array form.
+ */
+export type ParamValue = boolean | number | string | Record<string, unknown> | unknown[];
+/** How a param's wire value is encoded (when it isn't a plain scalar). */
+export type ParamEncoding = "base64+json" | "json";
+/** A live property value plus the param_type it came from. */
+export interface PropertyValue {
+    name: string;
+    paramType: number;
+    value: ParamValue;
+    /** When the value was last observed (epoch ms). */
+    ts: number;
+}
+/**
+ * One property whose value moved — the payload of a property-change announcement.
+ *
+ * Identified by property NAME and nothing else. The name is unique per device, is what `applyParams`
+ * already answers with, and is the key `Device.getProperty` takes — so a caller can re-read
+ * immediately. No wire id travels with it: resolving several ids to one property is the whole job the
+ * param → spec map does, and handing the id back out undoes it and gives a caller a second identifier
+ * to key on, which then breaks on the family where that property's read alias is promoted. The ids stay
+ * available through `inspectDevice` and `Device.describe()`.
+ *
+ * The capability accessor behind the name is published by `Device.describe()` as the
+ * `{ accessor, property }` pair, joined once at setup.
+ */
+export interface PropertyChange {
+    /** The property whose value moved — a key of this device's own schema. */
+    property: string;
+    /**
+     * What {@link Device.getProperty} now serves for this property, narrowed to its declared type the same
+     * way a capability getter narrows it.
+     *
+     * Read out of live state, never re-converted from the wire, so it cannot disagree with the getter
+     * beside it. Said as "what `getProperty` serves" rather than "what the getter answers" because a
+     * schema property does not always HAVE a typed getter: an `unexposed` member is reported and readable
+     * but has no confirmed meaning for its value, so promising the getter here would be a claim this SDK
+     * has not made anywhere else.
+     *
+     * Absent where no scalar can honestly be given: a property whose stored value is a PAYLOAD rather than
+     * the value (see {@link PropertySpec.raw}), and one whose stored value does not match its declared
+     * type. In both cases the honest answer is "this moved, re-read it".
+     */
+    value?: boolean | number | string;
+}
+/**
+ * A capability module = property schema + detection + inbound decode + outbound commands.
+ * Written ONCE, reused by every device that lists the capability. This is how "extra bits" (a
+ * camera's light, pan-tilt, doorbell button) attach without subclassing. The full shape lives in
+ * `capabilities/types.ts`; re-exported here so existing `./types` importers keep working.
+ */
+export type { CapabilityModule, DetectionSpec, CapabilityFrame, CapabilityEvent, CommandContext, AvailabilityContext, CapabilityActions, } from "./capabilities/types.js";
+/**
+ * A curated registry row (tier 1). Keyed by model (T-code) in the registry. Everything is
+ * optional except `codec` — capabilities can also come from the category default or inference.
+ */
+export interface RegistryEntry {
+    codec: Codec;
+    /** Capabilities to attach in addition to the codec's baseline. */
+    caps?: Capability[];
+    /** Pretty display name. */
+    name?: string;
+    /**
+     * Per-device one-off behaviour. Quarantined to this row — the escape hatch that replaces
+     * subclassing. Keys are command names; values are device-specific implementations.
+     */
+    overrides?: Record<string, unknown>;
+}
+/**
+ * The minimal slice of a cloud device record the model needs to classify + infer. The real
+ * record (`EufyDevice.raw`) has far more; we read only these.
+ */
+export interface CloudRecord {
+    /** eufy's own numeric DeviceType (authoritative classifier). */
+    deviceType?: number;
+    /** Model / product code (T-code), e.g. "T8423". */
+    model?: string;
+    /** Anker category string, e.g. "eufy_security". */
+    category?: string;
+    /**
+     * What the user named this device in the app (`device_name`), when the record carries one. Not a
+     * classification signal — carried so a device answers with the name its owner sees.
+     */
+    name?: string;
+    /**
+     * The parent HomeBase's serial when this device hangs off one (`parent_sn` ≠ own sn); absent when
+     * the device stands alone. A topology signal, not a param — used by {@link resolveDevice} to withhold
+     * station-scoped capabilities (guard-mode `arming`) from a camera behind a HomeBase, where the
+     * HomeBase owns them.
+     */
+    parentSn?: string;
+    /** Reported param_type → raw value. Presence of a param is a capability signal. */
+    params?: Record<number, string>;
+}
+/** The fully-resolved device shape produced by the 3-tier resolver. */
+export interface ResolvedDevice {
+    codec: Codec;
+    capabilities: Capability[];
+    /** Merged, de-duplicated property schema from all resolved capabilities. */
+    properties: PropertySpec[];
+    /** Display name (curated row → inferred → model code). */
+    name: string;
+    /** How the codec/caps were resolved, for diagnostics. */
+    source: "model" | "category" | "inferred";
+}

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

@@ -0,0 +1,92 @@
+import type { MapPose, VacuumMapBackup, VacuumMapDescription, VacuumMapPlane, VacuumRestrictedZones, VacuumRoom, VacuumRoomOutline, VacuumRoomParams } from "./vacuum-map.js";
+/** Everything the store currently holds about one map. Any piece may be absent until it arrives. */
+export interface VacuumMapSnapshot {
+    /**
+     * Which map these pieces describe, or `undefined` when nothing carrying an id has arrived yet.
+     *
+     * A robot with several floors saved sends whichever is loaded. When this changes, every piece below
+     * is from the new map — the store does not merge across maps.
+     */
+    readonly mapId: number | undefined;
+    readonly plane: VacuumMapPlane | undefined;
+    readonly outline: VacuumRoomOutline | undefined;
+    readonly rooms: VacuumRoomParams | undefined;
+    readonly zones: VacuumRestrictedZones | undefined;
+    readonly description: VacuumMapDescription | undefined;
+    /**
+     * Where the robot was when it last said so.
+     *
+     * Kept across a map switch, unlike everything else: a pose is a position in the world and does not
+     * belong to a map. It may fall outside the new map's bounds, in which case a lookup answers nothing.
+     */
+    readonly pose: MapPose | undefined;
+}
+/** A piece the store can be given, tagged by which one it is. */
+export type VacuumMapPiece = {
+    readonly kind: "plane";
+    readonly value: VacuumMapPlane;
+} | {
+    readonly kind: "outline";
+    readonly value: VacuumRoomOutline;
+} | {
+    readonly kind: "rooms";
+    readonly value: VacuumRoomParams;
+} | {
+    readonly kind: "zones";
+    readonly value: VacuumRestrictedZones;
+} | {
+    readonly kind: "description";
+    readonly value: VacuumMapDescription;
+} | {
+    readonly kind: "pose";
+    readonly value: MapPose;
+} | {
+    readonly kind: "backup";
+    readonly value: VacuumMapBackup;
+};
+/**
+ * Holds the current map for one device, and answers questions about it.
+ *
+ * Created empty and filled by {@link VacuumMapStore.apply}. Every getter answers `undefined` until the
+ * pieces it needs have arrived, rather than answering from a partial map.
+ */
+export declare class VacuumMapStore {
+    private current;
+    /** The highest revision seen per piece, so an out-of-order repeat cannot overwrite a newer one. */
+    private readonly revisions;
+    /** What the store holds right now. A new object whenever anything changed, the same one when not. */
+    get snapshot(): VacuumMapSnapshot;
+    /**
+     * Take one piece, and say whether it changed anything.
+     *
+     * `false` means the piece was stale — an older revision of a map already held — and was dropped. The
+     * device repeats its map frequently, so the return is what tells a repeat from a change.
+     */
+    apply(piece: VacuumMapPiece): boolean;
+    /** Forget everything. For a device going away, or a caller starting over. */
+    clear(): void;
+    /**
+     * Which room the robot is standing in, or `undefined`.
+     *
+     * `undefined` covers every honest reason there is no answer: no pose yet, no room outline yet, no
+     * room list yet, a robot outside the mapped area, or a cell belonging to no room. None of those is
+     * an error, and none should be reported as a guess.
+     */
+    get currentRoom(): VacuumRoom | undefined;
+    /**
+     * Apply a whole `MapBackup` as the several pieces it contains.
+     *
+     * Each part goes through the same path a lone piece takes, so a backup cannot install something a
+     * live frame would have rejected. Parts the device omitted are skipped rather than clearing what is
+     * held: a backup carrying only a description is a rename.
+     */
+    private applyBackup;
+    /**
+     * Store one stamped piece, dropping it when it is older than the piece of its kind already held.
+     *
+     * The map-switch check comes first and is the important one: a piece naming a different map is not
+     * an update, it is a different map. Everything held describes the old one, and a room outline read
+     * with the new map's coordinates gives a wrong answer that looks exactly like a right one.
+     */
+    private put;
+}