@mega-yfue/eufy-sdk 0.2.0-beta.2 → 0.2.0-beta.21

package/dist/model/capabilities/vacuum-clean.d.ts

@@ -192,35 +192,27 @@ export declare const ModeCtrlMethod: {
     readonly STOP_SMART_FOLLOW: 18;
     readonly START_GLOBAL_CRUISE: 20;
 };
-/**
- * The methods that carry a `Param` oneof — room, zone, goto, schedule, cruise and scene cleans.
- *
- * Deliberately absent from {@link ModeCtrlMethod}. Each needs an argument the caller has to supply and
- * this SDK cannot yet answer: a room or zone id comes from map data, which is not decodable here, and a
- * coordinate is signed centimetres in a frame no capture has pinned. Listing their numbers beside the
- * parameterless ones would invite a caller to send one with an empty payload, which is a valid frame
- * meaning something nobody intended.
- */
-/**
- * Encode a `ModeCtrlRequest` protobuf (DP 152) as a DP value: `varint(bodyLen) ++ {method:1, seq:2}`.
- *
- * Built on {@link RawDpWriter} rather than hand-rolled bytes. The frame is unchanged and the existing
- * byte-level test is what proves it — that test was written against a live T2351 capture, so it holds
- * the writer to the wire rather than to this function's own idea of the wire.
- *
- * Method 0 (START_AUTO_CLEAN) is omitted rather than written as an explicit zero, per the proto3
- * default-field rule and confirmed on that same capture. The writer deliberately does not apply that
- * rule itself: whether an explicit zero and an absent field mean the same thing is the
- * message's business, not the encoder's.
- * @internal
- */
 /**
  * The area-selecting `ModeCtrlRequest` methods, and the `Param` field each one's payload rides in.
  *
  * Kept apart from {@link ModeCtrlMethod} because these are a different kind of thing: a parameterless
  * verb is complete on its own, whereas each of these is meaningless without an argument the caller has
  * to supply. Sending one with an empty payload is a well-formed frame that means something nobody
- * intended, which is exactly why the numbers do not sit beside the others.
+ * intended, which is exactly why the numbers do not sit beside the others. Each verb built on one takes
+ * its argument in the signature: {@link VACUUM_CLEAN_MEMBERS.startScene},
+ * {@link VACUUM_CLEAN_MEMBERS.cleanRooms} and {@link VACUUM_CLEAN_MEMBERS.cleanZones}.
+ *
+ * The outer frame these ride in is byte-verified on a live T2351, and `SCENE`, `SELECT_ROOMS` and
+ * `SELECT_ZONES` have each since been RUN on a T2351 and did what they name — so their numbers rest on
+ * observed behaviour rather than on the vendor's definition alone.
+ *
+ * That distinction is the whole point of checking, and this is the one place it is argued: an AIoT
+ * data-point write is fire-and-forget, so a wrong number would be a different command arriving and
+ * looking exactly like success, which no frame check could catch. Watching the number is the only thing
+ * that rules it out.
+ *
+ * `GOTO` carries no encoder because a goto point is a coordinate no read on this SDK supplies, where a
+ * scene id and a map id both arrive on DP 180.
  */
 export declare const ModeCtrlParamMethod: {
     /** `START_SELECT_ROOMS_CLEAN` — clean the named rooms of a named map. */
@@ -267,7 +259,7 @@ export interface VacuumZoneTarget {
  * `mapId` is required and has no default, deliberately. The obvious shortcut is to assume the map a
  * single-floor home would have; on a two-floor home that silently sends the robot's ids against the
  * wrong floor's map. A caller that cannot name the map cannot safely make this call, and saying so is
- * better than picking for them.
+ * better than picking for them. {@link VACUUM_CLEAN_MEMBERS.cleanRooms} dispatches this.
  * @internal
  */
 export declare function encodeSelectRoomsClean(mapId: number, rooms: readonly VacuumRoomTarget[], cleanTimes?: number): string;
@@ -276,8 +268,25 @@ export declare function encodeSelectRoomsClean(mapId: number, rooms: readonly Va
  * @internal
  */
 export declare function encodeSelectZonesClean(mapId: number, zones: readonly VacuumZoneTarget[]): string;
-/** Build a scene clean, which needs only the scene's own id. @internal */
+/**
+ * Build a scene clean, which needs only the scene's own id — `VacuumScene.id`, as DP 180 reports it.
+ * {@link VACUUM_CLEAN_MEMBERS.startScene} dispatches this.
+ * @internal
+ */
 export declare function encodeSceneClean(sceneId: number): string;
+/**
+ * Encode a `ModeCtrlRequest` protobuf (DP 152) as a DP value: `varint(bodyLen) ++ {method:1, seq:2}`.
+ *
+ * Built on {@link RawDpWriter} rather than hand-rolled bytes. The frame is unchanged and the existing
+ * byte-level test is what proves it — that test was written against a live T2351 capture, so it holds
+ * the writer to the wire rather than to this function's own idea of the wire.
+ *
+ * Method 0 (START_AUTO_CLEAN) is omitted rather than written as an explicit zero, per the proto3
+ * default-field rule and confirmed on that same capture. The writer deliberately does not apply that
+ * rule itself: whether an explicit zero and an absent field mean the same thing is the
+ * message's business, not the encoder's.
+ * @internal
+ */
 export declare function encodeModeCtrl(method: number, seq: number): string;
 /**
  * Every value {@link VacuumActivity} can take, as data — the read's declared domain, so the schema a
@@ -1941,6 +1950,46 @@ export declare const VACUUM_CLEAN_MEMBERS: {
     readonly pauseCleaning: import("./members.js").MethodMember<() => Promise<void>> & {
         available: (ctx: import("./types.js").CommandContext) => boolean;
     };
+    /**
+     * Run a saved cleaning scene by its id (ModeCtrlRequest method 24 over DP 152).
+     *
+     * The id is the device's own, as {@link VACUUM_CLEAN_MEMBERS.scenes} reports it — `VacuumScene.id`
+     * off the `SceneResponse` on DP 180. A scene the device reports invalid stays reportable and running
+     * it is still a well-formed request; `VacuumScene.invalidReason` says why the device will refuse.
+     *
+     * Frame shape is byte-proven against the shared outer `ModeCtrlRequest`, and method 24 has been
+     * WATCHED: run on a T2351, it started the named scene.
+     */
+    readonly startScene: import("./members.js").MethodMember<(sceneId: number) => Promise<void>> & {
+        available: (ctx: import("./types.js").CommandContext) => boolean;
+    };
+    /**
+     * Clean the named rooms of a named map (ModeCtrlRequest method 1 over DP 152).
+     *
+     * `mapId` has no default and that is deliberate: room ids are per map, so assuming the map a
+     * single-floor home would have sends a two-floor home's ids against the wrong floor. `SceneInfo.mapid`
+     * on DP 180 and a scheduled rooms-clean's `map_id` are the two real map ids the device reports.
+     *
+     * `cleanTimes` is how many passes to make over the set; rooms with no `order` are visited in the
+     * order given.
+     *
+     * Frame shape is byte-proven against the shared outer `ModeCtrlRequest`, and method 1 has been
+     * WATCHED: run on a T2351, it cleaned the rooms named.
+     */
+    readonly cleanRooms: import("./members.js").MethodMember<(mapId: number, rooms: readonly VacuumRoomTarget[], cleanTimes?: number) => Promise<void>> & {
+        available: (ctx: import("./types.js").CommandContext) => boolean;
+    };
+    /**
+     * Clean the given rectangles of a named map (ModeCtrlRequest method 2 over DP 152).
+     *
+     * Corners are SIGNED centimetres in the map's own frame, whose origin sits wherever the robot first
+     * mapped from — negative coordinates are ordinary and are ZigZag-encoded, not written as plain
+     * varints. Same `mapId` reasoning as {@link VACUUM_CLEAN_MEMBERS.cleanRooms}, and the same evidence:
+     * method 2 was run on a T2351 and cleaned the rectangles given.
+     */
+    readonly cleanZones: import("./members.js").MethodMember<(mapId: number, zones: readonly VacuumZoneTarget[]) => Promise<void>> & {
+        available: (ctx: import("./types.js").CommandContext) => boolean;
+    };
 };
 /** `vacuum_clean` — core RoboVac scalar state + decoded activity: power, activity, volume, battery. */
 export declare const VACUUM_CLEAN: CapabilityModule;

package/dist/model/device.d.ts

@@ -62,6 +62,11 @@ export declare class Device {
      * different wire ids across device families still resolves to one named value.
      */
     private specByParam;
+    /**
+     * Params a resolved capability declares that this device's schema does not carry — withheld by a
+     * member's gate, so not named from the param dictionary either. See {@link Device.applyParams}.
+     */
+    private withheld;
     /** 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. */
@@ -201,6 +206,16 @@ export declare class Device {
      * 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.
      *
+     * Naming precedence: this device's own `PropertySpec` (curated), then the param dictionary for its
+     * namespace, then the `unknown_<paramType>` passthrough. The dictionary def is consulted even where a
+     * spec exists, because `encoding` lives there.
+     *
+     * A param a resolved capability's gate WITHHELD takes the passthrough instead of its dictionary name.
+     * The gate decided the read does not describe this device, the dictionary names it what the member
+     * would have, and republishing it there hands a caller a reading indistinguishable from one the device
+     * really answered. A capability that never resolved withholds nothing: a param arriving before its
+     * capability is still the device's own, and keeps its dictionary name.
+     *
      * @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.

package/dist/model/index.d.ts

@@ -30,3 +30,8 @@ export * from "./capabilities/index.js";
  */
 export type { FamilyContext } from "./device-family.js";
 export { CusPushEvent, CusPushAlarmType, CusPushMode, DoorbellPushEvent, IndoorPushEvent, HB3PairedDevicePushEvent, LockPushEvent, SmartDropPushEvent, NotificationStyle, detectionName, } from "./push-events.js";
+export { SolixDevice, discoverSolixDevices, solarbankSceneReadings, type SolixDeviceReader, type SolixDeviceRecord, type SolixIdentity, type SolixConnectivity, type SolixEnergyMeter, type SolixDeviceOptions, } from "./solix-device.js";
+export { SOLIX_ENERGY_METER_MEMBERS, type SolixCapability, type SolixEnergyMeterReads } from "./capabilities/solix.js";
+export { buildModelIndex, type SolixProduct, type SolixProductCategory } from "./solix-catalog.js";
+export { solixProductFamily, isSolixPowerStation, isSolixSolarbank, isSolixSmartMeter, type SolixProductFamily, type SolixFamilyInput, } from "./solix-family.js";
+export { SolixSite, discoverSolixSites, type SolixSiteReader, type SolixSiteOptions } from "./solix-site.js";

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

@@ -26,3 +26,27 @@ export interface ParamDef {
 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>;
+/**
+ * eufy Smart Display (T87Ax) param space — ids 8001-8006.
+ *
+ * Its own table rather than a corner of {@link SECURITY_PARAMS}: nothing in the 8000s carries a security
+ * meaning, so reading these ids there would decode a future security param assigned in this range as
+ * whatever it means on a camera.
+ *
+ * Every id here was reported by a live T87A0 (captured 2026-09-04). That the device SENT an id is what
+ * earns it a place in this table; the provenance label beside each one rates something narrower — how far
+ * its NAME is trusted. `modelName` and `modelCode` are `mega`, their values matching what the cloud
+ * record already carried. `battery` is `verified`: the id is real and the reading consistent, but the
+ * name came from the maintainer's own knowledge of the hardware rather than from the cloud data-point
+ * list, and `"100"` fits brightness, volume or charge equally.
+ *
+ * A dictionary entry is what makes a param readable by name off `getProperties()`. `capabilities/display.ts`
+ * decides separately which of them reach the typed surface, and only `battery` does.
+ *
+ * **8002 (`"1"`) and 8004 (a serial-shaped string) are absent, deliberately.** Neither meaning is
+ * legible from one value: `1` fits any enum or flag, and a serial could be the display's own or the
+ * station's it is bound to. They arrive as `unknown_8002` / `unknown_8004`, which is the measure of this
+ * list: it holds what is unknown, not what is unknowable. What would settle them: the vendor app's own
+ * display settings screen, one control at a time, params diffed after each.
+ */
+export declare const DISPLAY_PARAMS: Record<number, ParamDef>;

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

@@ -14,7 +14,7 @@
 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";
+export type ParamNamespace = "security" | "clean" | "life" | "print" | "display";
 /** 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. */

package/dist/model/solix-catalog.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Anker Solix product catalog — the vendor's pairable-product registry (categories → products),
+ * used to label a discovered device's model code with a marketing name + category.
+ *
+ * This is model-layer vocabulary: pure data shapes + a lookup builder, with no wire/transport
+ * dependency. The catalog itself is fetched from the cloud by the client layer (`SolixClient`), which
+ * feeds it here via {@link buildModelIndex}; keeping the shapes and the index in the model layer lets
+ * `SolixDevice` resolve a name/category without reaching across the capability↔transport boundary.
+ */
+export type { SolixProduct, SolixProductCategory } from "../core/solix-types.js";
+import type { SolixProductCategory } from "../core/solix-types.js";
+/**
+ * Flatten a product catalog into a `product_code → { name, category }` lookup for labelling
+ * discovered devices. Every variant code in `p_codes` maps to its parent product too, so a device
+ * reporting a sub-model resolves to the same marketing name.
+ *
+ * The category name is trimmed here, at ingest — the live catalog returns some names with trailing
+ * whitespace (e.g. `"Plug-in Home Battery "`), and normalising once at the source means every consumer
+ * (a device's `identity().category`, `detectSolixCapabilities`, and any exact-match category test) sees
+ * the clean name, rather than each call site having to remember to trim.
+ */
+export declare function buildModelIndex(categories: SolixProductCategory[]): Map<string, {
+    name: string;
+    category: string;
+}>;

package/dist/model/solix-device.d.ts

@@ -0,0 +1,136 @@
+import { type SolixCapability, type SolixEnergyMeterReads } from "./capabilities/solix.js";
+import { type SolixProductFamily } from "./solix-family.js";
+import type { SolixDeviceRecord, SolixProductCategory, SolixSiteScene } from "../core/solix-types.js";
+/**
+ * The device record shape, re-exported from the model surface. It lives in `core/solix-types` so the
+ * transport client can return it without crossing the transport↔model line.
+ */
+export type { SolixDeviceRecord } from "../core/solix-types.js";
+export interface SolixIdentity {
+    serial: string;
+    productCode: string;
+    /** Friendly name — the catalog marketing name if resolvable, else the record's alias/name. */
+    name: string;
+    /** Anker catalog category (e.g. "Accessory", "Portable Power Station"), if resolvable. */
+    category?: string;
+    /**
+     * Normalized product family — the "what kind of thing is this" answer (power station, Solarbank,
+     * smart meter, …), decorrelated from the marketing `category` string. See {@link SolixDevice.family}.
+     */
+    family: SolixProductFamily;
+}
+export interface SolixConnectivity {
+    online: boolean;
+    rssi?: number;
+    ssid?: string;
+}
+/**
+ * The `dev.energyMeter()` handle: the members-derived reads ({@link SolixEnergyMeterReads} —
+ * `meterVoltageL1` is present only once a frame carrying its tag has landed). Every not-yet-named meter
+ * quantity is read from {@link SolixDevice.telemetry} under its `channel_<hex tag>` key instead, which a
+ * static members table cannot enumerate.
+ */
+export type SolixEnergyMeter = SolixEnergyMeterReads;
+/** Options for {@link SolixDevice}. */
+export interface SolixDeviceOptions {
+    /** Catalog categories (from `SolixClient.getProductCatalog()`) — used to resolve name + category. */
+    catalog?: SolixProductCategory[];
+}
+/**
+ * A discovered Solix device with resolved category + capabilities. Feed live telemetry with
+ * {@link applyReading} (from {@link SolixMqtt}'s `reading` events) to populate value accessors.
+ */
+export declare class SolixDevice {
+    readonly serial: string;
+    readonly productCode: string;
+    readonly record: SolixDeviceRecord;
+    private readonly caps;
+    private readonly identity_;
+    private values;
+    constructor(record: SolixDeviceRecord, opts?: SolixDeviceOptions);
+    /**
+     * The device's {@link SolixProductFamily} — the classification a caller branches on to SORT devices
+     * (a site's power stations vs its meters), the Solix analogue of eufy's `isHomeBase()`. Distinct from
+     * {@link has}, which answers what the device can DO; family answers what KIND of device it is.
+     */
+    get family(): SolixProductFamily;
+    /** All capabilities this device carries. */
+    get capabilities(): SolixCapability[];
+    /** Whether the device carries a capability — the only correct way to branch on behaviour. */
+    has(capability: SolixCapability): boolean;
+    /**
+     * Merge a live telemetry reading (a `SolixMqtt` `reading` event) so accessors reflect it. Takes the
+     * WHOLE reading, not just its values, and drops one addressed to a different device: the documented
+     * wiring is `mqtt.on("reading", r => device.applyReading(r))`, and one MQTT stream carries every
+     * watched meter on the account — so without this filter two meters would cross-feed each other's floats.
+     * A reading with no `deviceSn` (a hand-built one) is accepted as-is.
+     */
+    applyReading(reading: {
+        deviceSn?: string;
+        values: Record<string, number>;
+    }): void;
+    /** All decoded float telemetry channels from the latest applied reading (raw, `channel_<tag>` keys). */
+    telemetry(): Record<string, number>;
+    identity(): SolixIdentity;
+    firmware(): {
+        version: string;
+    } | undefined;
+    connectivity(): SolixConnectivity | undefined;
+    /**
+     * The members-derived `energyMeter` reads, or `undefined` when the device has no meter. Each getter is
+     * installed only for a tag this device has actually reported, and reads `this.values` LIVE — a handle
+     * held across an {@link applyReading} reflects the newer values. Getter INSTALLATION is fixed at the
+     * time of this call, so re-call it to pick up a tag first seen since.
+     */
+    energyMeter(): SolixEnergyMeter | undefined;
+    /**
+     * The {@link MemberDeps} the members engine needs: a read closure over the live values store, and the
+     * evidence gate (`ctx.paramIds`) rebuilt from the ff09 tags this device has reported. No `codec` — the
+     * codecs are eufy transport families and a Solix device belongs to none of them. The sink is a no-op:
+     * Solix telemetry is read-only, no member here dispatches a command.
+     */
+    private meterDeps;
+    /** The ff09 tags this device has reported, derived from the decoder's `channel_<hex>` keys. */
+    private seenTags;
+}
+/**
+ * The minimum a client must offer to be discovered against — the two wire reads {@link discoverSolixDevices}
+ * composes. Typed STRUCTURALLY (not as `SolixClient`) so the model layer never imports the transport
+ * client: the hard `transport ⊥ model` rule forbids it, and a structural shape needs no import.
+ */
+export interface SolixDeviceReader {
+    getDevices(): Promise<SolixDeviceRecord[]>;
+    getProductCatalog(): Promise<SolixProductCategory[]>;
+}
+/**
+ * Resolve the product catalog for a discovery: a caller-supplied `opts.catalog` short-circuits the wire
+ * read, and a failed `getProductCatalog()` degrades to no categories (names/families just go unresolved,
+ * never a thrown discovery). Shared by {@link discoverSolixDevices} and `discoverSolixSites` so that
+ * "a failed catalog is non-fatal" decision lives in exactly one place.
+ */
+export declare function resolveSolixCatalog(client: SolixDeviceReader, opts: {
+    catalog?: SolixProductCategory[];
+}): Promise<SolixProductCategory[]>;
+/**
+ * Discover an account's Solix devices as capability-driven {@link SolixDevice} objects — the wire+model
+ * composition (a transport read + the product catalog) that used to be `SolixClient.discoverDevices()`.
+ * It lives in the model layer because it builds `SolixDevice`; the wire client (now `transport/http`)
+ * cannot, and passing it structurally keeps the layers decorrelated. Feed live telemetry to each result
+ * via `SolixDevice.applyReading`.
+ */
+export declare function discoverSolixDevices(client: SolixDeviceReader, opts?: {
+    catalog?: SolixProductCategory[];
+}): Promise<SolixDevice[]>;
+/**
+ * Reduce a site "scene" snapshot to per-device telemetry readings — the BACKSTOP counterpart to the
+ * realtime `ff09` decode. It emits only the fields the scene reliably carries that the fast MQTT frame
+ * does NOT: `batteryTemperature` (the realtime frame's BMS blob is empty, so `solixReadings` withholds
+ * it) and `batterySoc` (a cross-check/seed for the `0xa3` SOC). Each reading is shaped exactly like a
+ * `SolixMqtt` `reading` event — `{ deviceSn, values }` — so a caller can feed it straight into
+ * {@link SolixDevice.applyReading} and broadcast it on the same path as a live frame. Entries with no
+ * usable value are dropped, so a poll during a gap emits nothing rather than clobbering live values.
+ */
+export declare function solarbankSceneReadings(scene: SolixSiteScene): {
+    deviceSn: string;
+    values: Record<string, number>;
+}[];

package/dist/model/solix-family.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A Solix device's product family — the normalized "what kind of thing is this" answer, decorrelated
+ * from the Anker catalog's marketing category strings. `unknown` when neither the product code nor the
+ * category identifies a family (never a guess).
+ */
+export type SolixProductFamily = "powerStation" | "solarbank" | "smartMeter" | "powerBank" | "cooler" | "evCharger" | "charger" | "unknown";
+/** The pure evidence a family decision reads: the product code, and the catalog category when resolved. */
+export interface SolixFamilyInput {
+    /** SKU / model code, e.g. `A1782`, `AE103`, `AE1X0`. */
+    product_code: string;
+    /** Anker catalog category, when a catalog resolved one (e.g. `"Portable Power Station"`). */
+    category?: string;
+}
+/** Grid-tie Solarbank / plug-in home battery family (by product code, catalog-independent). */
+export declare const isSolixSolarbank: (input: SolixFamilyInput) => boolean;
+/** Smart energy meter / grid-CT family (by product code, catalog-independent). */
+export declare const isSolixSmartMeter: (input: SolixFamilyInput) => boolean;
+/** Portable Power Station (SOLIX F-series) family — resolved from the catalog category. */
+export declare const isSolixPowerStation: (input: SolixFamilyInput) => boolean;
+/**
+ * Resolve a Solix device's {@link SolixProductFamily} by consulting the family predicates first (they are
+ * catalog-independent, so a device classifies even before a catalog is fetched), then the catalog
+ * category for the families that have no prefix set yet. Returns `"unknown"` when neither identifies one —
+ * never a guess, mirroring `device-family.ts` returning `false` on an unknown device type.
+ *
+ * The meter is checked before the Solarbank: both can present a battery-ish catalog category, but the
+ * meter's `AE1X0` prefix is unambiguous and a meter is never a Solarbank. The Solarbank case reuses
+ * {@link isSolixSolarbank} (prefix OR the home-battery category) rather than re-testing the prefix here,
+ * so the two never drift.
+ */
+export declare function solixProductFamily(input: SolixFamilyInput): SolixProductFamily;

package/dist/model/solix-site.d.ts

@@ -0,0 +1,70 @@
+/**
+ * A capability-driven model for an Anker Solix **site** — the account's home energy system, the "My
+ * Home" the app shows. A site is the Solix analogue of a eufy HomeBase in its GROUPING role: it is the
+ * system that member devices belong to, so it is what a caller reaches for to ask "what's in this
+ * system" and to sort the members by family ({@link SolixSite.powerStations} / {@link solarbanks} /
+ * {@link smartMeters}) or by capability ({@link SolixSite.withCapability}).
+ *
+ * A site is a *grouping*, not a device: it carries no telemetry of its own. Its members are full
+ * {@link SolixDevice} models (each with its own capabilities + live telemetry), resolved by
+ * {@link discoverSolixSites} from the site record's member list joined to the account's device records.
+ * The realtime SYSTEM aggregate the app draws (instantaneous battery SoC + solar + grid flow) is not
+ * modelled here: it has no confirmed, stable read surface for the current device generation, and this
+ * layer does not fabricate a getter for a value it cannot ground — a caller reads each member device's
+ * telemetry instead.
+ */
+import { SolixDevice, type SolixDeviceReader } from "./solix-device.js";
+import type { SolixProductFamily } from "./solix-family.js";
+import type { SolixCapability } from "./capabilities/solix.js";
+import type { SolixProductCategory, SolixSiteRecord } from "../core/solix-types.js";
+/**
+ * The minimum a client must offer to discover an account's SITES against — {@link SolixDeviceReader}
+ * (the device + catalog reads {@link discoverSolixDevices} already composes) plus the site read.
+ * Structural (not `SolixClient`) so the model layer never imports the transport client: the hard
+ * `transport ⊥ model` rule forbids it, and a structural shape needs no import.
+ */
+export interface SolixSiteReader extends SolixDeviceReader {
+    getSites(): Promise<SolixSiteRecord[]>;
+}
+/** Options for {@link SolixSite} / {@link discoverSolixSites} — the same catalog the device model takes. */
+export interface SolixSiteOptions {
+    catalog?: SolixProductCategory[];
+}
+/**
+ * A discovered Solix site with its member devices resolved to {@link SolixDevice} models. Build one
+ * directly from a record + members, or discover an account's sites with {@link discoverSolixSites}.
+ */
+export declare class SolixSite {
+    readonly id: string;
+    /** Friendly site name (e.g. "My Home"), or the site id when the record carries none. */
+    readonly name: string;
+    /** Anker's site-type discriminator (e.g. 20 for a Solarbank-anchored home system), when present. */
+    readonly powerSiteType?: number;
+    readonly record: SolixSiteRecord;
+    readonly devices: SolixDevice[];
+    constructor(record: SolixSiteRecord, devices: SolixDevice[]);
+    /** The member device with this serial, if it belongs to the site. */
+    device(serial: string): SolixDevice | undefined;
+    /** Member devices of a given product {@link SolixProductFamily} — the grouping accessor. */
+    withFamily(family: SolixProductFamily): SolixDevice[];
+    /** Member devices that carry a given capability (e.g. every `battery` in the system). */
+    withCapability(capability: SolixCapability): SolixDevice[];
+    /** The Solarbank / plug-in home-battery members of the system. */
+    solarbanks(): SolixDevice[];
+    /** The smart-meter (grid-CT) members of the system. */
+    smartMeters(): SolixDevice[];
+    /** The portable power-station members of the system. */
+    powerStations(): SolixDevice[];
+}
+/**
+ * Discover an account's Solix sites as {@link SolixSite} groupings of capability-driven
+ * {@link SolixDevice} members — the site analogue of {@link discoverSolixDevices}. Composes three wire
+ * reads (the sites, the account's device records, the product catalog) entirely model-side, so the
+ * transport client is passed structurally and the layers stay decorrelated.
+ *
+ * A site member is resolved to its FULL device record from `getDevices()` when the account lists one
+ * (so the member carries firmware/connectivity + telemetry identity); a member the flat device list
+ * omits is built from the site entry alone (serial + product code + name), so the system is never
+ * missing a device it declares.
+ */
+export declare function discoverSolixSites(client: SolixSiteReader, opts?: SolixSiteOptions): Promise<SolixSite[]>;

package/dist/model/types.d.ts

@@ -28,10 +28,10 @@
  *
  * `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).
+ * `p2p_did`, never P2P). It owns its own param namespace (ids 8001-8006) and its own product line, so
+ * no other line's capability can attach to it — see `namespaceForCodec` and `CODEC_LINE`. The `display`
+ * capability targets it and reads the charge; no screen/audio/assistant param has been observed, so
+ * those are absent rather than deferred.
  */
 export type Codec = "station" | "camera" | "sensor" | "lock" | "keypad" | "vacuum" | "mower" | "light" | "printer" | "display";
 /**
@@ -39,7 +39,7 @@ export type Codec = "station" | "camera" | "sensor" | "lock" | "keypad" | "vacuu
  * 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";
+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" | "display" | "info";
 /** Value type of a property. */
 export type PropertyValueType = "bool" | "number" | "string" | "enum";
 /**

package/dist/transport/ff09.d.ts

@@ -397,6 +397,13 @@ export interface Ff09SettingsResponse {
  * padding past the last real field.
  */
 export declare function parseFf09SettingsResponse(plain: Buffer): Ff09SettingsResponse;
+/**
+ * Walk a bounded `tag|len|value` TLV region into a `tag → bytes` map. Stops at a `0x00` tag (only ever
+ * trailing zero-padding, never a real field — real tags start at `0xa1`) and refuses a field whose
+ * declared length would overrun `end`, so a corrupt length can't read past the region (e.g. into a
+ * trailing checksum). Shared by {@link parseFf09SettingsResponse} and the Solix param decoder.
+ */
+export declare function walkFf09Tlv(buf: Buffer, start: number, end: number): Map<number, Buffer>;
 /** Read a little-endian u16 out of a TLV field buffer (throws on a missing/short field — a caller-side bug, not a wire ambiguity). */
 export declare function readFf09U16LE(field: Buffer | undefined, name: string): number;
 /** Read a single byte out of a TLV field buffer (throws on a missing field — same convention as {@link readFf09U16LE}). */

package/dist/transport/http/decodeImageV2.d.ts

@@ -1,19 +1,13 @@
-/**
- * Per-channel auto-contrast, a byte-exact port of PIL `ImageOps.autocontrast` (cutoff 0.5%). The lost
- * quant tables leave the reconstruction low-contrast ("foggy"); stretching each channel's clipped range
- * to full scale restores a natural-looking image. Mutates `data` (RGBA) in place.
- *
- * Parity notes vs PIL: the cutoff count is `n * cutoff // 100` (integer floor); it is trimmed off each
- * end by zeroing whole histogram bins until the count is spent; the range is then the first/last
- * non-empty bins; and the LUT truncates toward zero (`int()`), NOT rounds — rounding would shift pixels.
- */
-export declare function autoContrast(data: Uint8Array, width: number, height: number, cutoff?: number): void;
 /** True if the blob is a v2 `v2_eufysecurity:` push thumbnail. */
 export declare function isV2Image(data: Buffer): boolean;
 /**
- * Decode a v2 blob to a plain JPEG buffer by reconstructing its header, or null if it isn't v2 or the
- * plaintext scan can't be located. The search first chooses subsampling and coarse geometry, derives
- * the fixed MCU count, refines width by row shear, and pins the exact fill height before applying
- * auto-contrast and re-encoding. See the module doc for the keyless-splice rationale.
+ * Decode a v2 blob to a plain JPEG buffer by reconstructing its header, or null if it isn't v2, the
+ * plaintext scan can't be located, or no frame shape explains it.
+ *
+ * Three steps and no pixel rewrite: the frame shape is read out of the entropy scan,
+ * one probe decode both proves the spliced JPEG decodes and measures how far the substitute quant
+ * tables fall short of the camera's, and the answer is the same tail under a header carrying the
+ * corrected tables. See the module doc for the keyless-splice rationale and for why neither the search
+ * nor the correction decodes candidate frames or re-encodes the picture.
  */
 export declare function decodeImageV2(data: Buffer): Buffer | null;

package/dist/transport/http/index.d.ts

@@ -3,3 +3,4 @@ export { randomPhoneModel, randomUserAgent } from "./phone-model.js";
 export * from "./decodeImageV1.js";
 export * from "./decodeImageV2.js";
 export { listLightEffects, listAiSceneRecommendations, type LightEffectSummary } from "./light-catalog.js";
+export { SolixClient, type SolixClientOptions, type SolixLoginResult, type SolixSession, type SolixPersisted, type SolixSessionStore, } from "./solix-client.js";

package/dist/transport/http/jpeg-scan.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A baseline-JPEG entropy scanner that decodes no pixels.
+ *
+ * The v2 thumbnail decoder next door has to discover a frame geometry its blob does not state, and the
+ * only evidence is the plaintext entropy-coded scan: how many MCUs it carries, and whether it carries
+ * them under a given chroma subsampling. A JPEG decoder answers that — it throws on a frame the scan
+ * does not fill — and charges a full set of component and output buffers for each question.
+ *
+ * That bill is fatal for a caller under a hard memory cap. Each `jpeg-js` decode churns roughly a
+ * megabyte of typed arrays, glibc keeps the arenas rather than handing them back, and a search asking
+ * the question of every candidate geometry costs tens of megabytes per thumbnail — permanently, and
+ * more than an embedded host gives an app in total.
+ *
+ * This module asks the same question by walking the Huffman-coded coefficients and throwing them away:
+ * no IDCT, no component planes, no output image. What it keeps is one number per MCU — the DC
+ * coefficient of its luma block(s), i.e. that block's average brightness — which is all the geometry
+ * search needs to tell a sheared row apart from a continuous one. Allocation is a single `Int32Array`
+ * of MCU count, and the walk is linear in the scan's length.
+ *
+ * Baseline sequential only (SOF0), which is what the v2 tail is: no progressive refinement, no
+ * arithmetic coding. Restart markers are tolerated — the scan resynchronises and resets its DC
+ * predictors, exactly as a decoder would.
+ *
+ * @module transport/http/jpeg-scan
+ */
+/** What the scan carried, under one subsampling hypothesis. */
+export interface EntropyScan {
+    /** Complete MCUs decoded before the data ran out. */
+    mcus: number;
+    /**
+     * Mean luma DC per MCU, in scan order — a thumbnail of the picture at MCU resolution.
+     *
+     * Quantized units (the quant tables are lost with the v2 head), so the values are a scale of their
+     * own. Differences between neighbours are what the geometry search reads, and those survive.
+     */
+    luma: Int32Array;
+    /**
+     * Whether the scan ended where a whole MCU ended, with nothing but the EOI marker left.
+     *
+     * The discriminator between hypotheses: a wrong one reads a block with the wrong Huffman table,
+     * diverges, and either dies mid-MCU or stops with data still ahead of it. Only the subsampling the
+     * encoder used walks the scan to its last byte on an MCU boundary.
+     */
+    complete: boolean;
+}
+/**
+ * Walk the plaintext tail's scan under one subsampling hypothesis.
+ *
+ * `extraTables` carries the DHT segments that are NOT in the tail — for a v2 thumbnail, the standard
+ * luma tables the reconstructed header supplies, since only the chroma ones survive in plaintext.
+ * Returns null when the tail is not a baseline scan at all (no SOS, missing tables).
+ *
+ * The walk stops at the first byte it cannot read as this hypothesis's next block, and the result is
+ * `complete` only when that happened on an MCU boundary with nothing but a marker left. The DC array
+ * grows as the scan turns out to be long rather than being sized from the scan's byte length: a wrong
+ * hypothesis dies after a handful of MCUs, and provisioning three whole-scan arrays to discover that is
+ * the kind of allocation this module exists to avoid.
+ */
+export declare function scanEntropy(tail: Uint8Array, subsampling: number, extraTables: readonly Uint8Array[]): EntropyScan | null;

package/dist/transport/http/media-download.d.ts

@@ -1,7 +1,10 @@
+import type { MediaFailureReason } from "../media-failure.js";
 type ResolveHost = (hostname: string) => Promise<readonly {
     address: string;
     family: number;
 }[]>;
+/** Tag a failure OUTSIDE the transfer itself — the push-image decoder refusing bytes that did arrive. @internal */
+export declare function mediaFailureError(message: string, reason: MediaFailureReason, cause?: unknown): Error;
 /** Signals rejection of the active Eufy session without exposing response content. @internal */
 export declare class MediaDownloadAuthenticationError extends Error {
 }