@mega-yfue/eufy-sdk 0.2.0-beta.17 → 0.2.0-beta.19

package/dist/model/capabilities/solix.d.ts

@@ -143,7 +143,18 @@ export declare const CATEGORY_CAPABILITIES: Readonly<Record<string, readonly Sol
 export declare const SOLIX_METER_MODELS: readonly string[];
 /**
  * Product-code prefixes for the grid-tie Solarbank / home-battery family (detects `battery` +
- * `solarInput` regardless of category): A1790 = Solarbank E1600 gen-1, A17C* = Solarbank 2 / 3.
+ * `solarInput` regardless of category, so a caller that builds a device without the catalog still gets
+ * them): `A1790` = Solarbank E1600 gen-1, `A17C*` = Solarbank 2 / 3, `AE10*` = Solarbank 4 E5000 Pro /
+ * SOLIX Power Dock.
+ *
+ * Grounded in the live `product_categories` catalog: `A17C0`–`A17C5` and `AE100` all list under
+ * category `"Plug-in Home Battery "`, and `AE103` by the device spec. `AE1X0`/`AE1R0` meters start
+ * `AE1X`/`AE1R`, so `AE10` does not catch them.
+ *
+ * The speculative `A17E` ("Solarbank Max AC") and `AE11` ("Solarbank Max") were dropped: neither is in
+ * the catalog, and the only `AE11x` product there — `AE113` "XE 6/8kW" — is a Residential Storage
+ * System, a different family whose telemetry is unverified, so granting it `battery`/`solarInput` would
+ * be an unevidenced false positive (exactly what this detection is otherwise careful to avoid).
  */
 export declare const SOLARBANK_MODELS: readonly string[];
 /** The minimum device shape {@link detectSolixCapabilities} reads. */

package/dist/model/capabilities/types.d.ts

@@ -247,7 +247,11 @@ export interface CommandContext extends AvailabilityContext {
     adminUserId?: string;
     /** The acting member's short id (`member.short_user_id`, hex, e.g. `"0003"`) — the lock cmd `A5` field. */
     shortUserId?: string;
-    /** The logged-in account's display name (email local-part) — the lock cmd acting-username `A4` field. */
+    /**
+     * The acting name a command attributes itself to — the lock cmd acting-username `A4` field, and the
+     * `user_name` of the guard-mode and HomeBase-alarm writes. The logged-in account's display name
+     * (email local-part) unless the client pins a different label for it.
+     */
     accountName?: string;
     /**
      * Whether the device has a usable P2P endpoint (a non-empty `p2p_did`). A HomeBase-attached lock

package/dist/model/index.d.ts

@@ -30,6 +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, type SolixDeviceReader, type SolixDeviceRecord, type SolixIdentity, type SolixConnectivity, type SolixEnergyMeter, type SolixDeviceOptions, } from "./solix-device.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/solix-catalog.d.ts

@@ -13,6 +13,11 @@ 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;

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

@@ -1,5 +1,6 @@
 import { type SolixCapability, type SolixEnergyMeterReads } from "./capabilities/solix.js";
-import type { SolixDeviceRecord, SolixProductCategory } from "../core/solix-types.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.
@@ -12,6 +13,11 @@ export interface SolixIdentity {
     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;
@@ -42,6 +48,12 @@ export declare class SolixDevice {
     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. */
@@ -90,6 +102,15 @@ 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()`.
@@ -100,3 +121,16 @@ export interface SolixDeviceReader {
 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/transport/http/mega-client.d.ts

@@ -32,6 +32,14 @@ export interface MegaClientConfig {
      * an explicit value pins a fixed one. Not the account identity — that's `phoneModel`.
      */
     mediaUserAgent?: string;
+    /**
+     * Acting name written into the commands that carry an actor field — guard mode and HomeBase alarm
+     * output (`user_name`), a lock's acting username. Trimmed, and blank counts as unset: the default
+     * is the login email's local-part (the whole string when it has no `@`). Attribution only — the
+     * device stores it for its own activity record, and no captured frame shows it being validated
+     * against the account.
+     */
+    accountName?: string;
     /** Persist + reuse the session (token + session key) across runs. Default: in-memory. */
     store?: SessionStore;
     /** Diagnostics sink. Omit for silence; pass a `Logger` (or `new ConsoleLogger()`) to see logs. */
@@ -238,10 +246,15 @@ export declare class MegaHttpClient {
     /** The active region shard (e.g. `"eu-pr"`, `"us-pr"`), set after {@link login} or a region override. */
     get regionShard(): RegionShard;
     /**
-     * The logged-in account's display name — the login email's local-part (e.g. `someone+tag` for
-     * `someone+tag@example.com`). This is the string the app writes into the ff09 command's acting
-     * "username" field (verified against a captured T8531 unlock frame). Falls back to the whole email
-     * if it has no `@`.
+     * The name commands attribute themselves to — {@link MegaClientConfig.accountName} when the config
+     * pins one (trimmed; blank counts as unset), otherwise the logged-in account's display name, which
+     * is the login email's local-part (e.g. `someone+tag` for `someone+tag@example.com`) and falls back
+     * to the whole email if it has no `@`.
+     *
+     * The local-part is the string the app writes into the ff09 command's acting "username" field
+     * (verified against a captured T8531 unlock frame), so it is the faithful default. An override is a
+     * different LABEL for the same account, not a different identity: the session authenticates on the
+     * token and the device record's member ids, neither of which this touches.
      */
     get accountName(): string;
     /**

package/dist/transport/http/solix-client.d.ts

@@ -14,7 +14,7 @@
  * those records into capability-driven `SolixDevice` models is the model layer's job — see
  * `discoverSolixDevices()` — so the two stay decorrelated (transport never imports model).
  */
-import { type SessionStore, type SolixDeviceRecord, type SolixProductCategory } from "../../core/index.js";
+import { type SessionStore, type SolixDeviceRecord, type SolixPowerCutoffOption, type SolixProductCategory, type SolixSiteRecord, type SolixSiteScene, type SolixSocParams } from "../../core/index.js";
 import type { SecureMqttCredentials } from "../mqtt/secure-mqtt.js";
 /** An authenticated Solix session — the token + the derived `gtoken` + the resolved API host. */
 export interface SolixSession {
@@ -136,11 +136,25 @@ export declare class SolixClient {
      * (adopted from a store) is answered without a handshake.
      */
     login(): Promise<SolixLoginResult>;
+    /**
+     * On a rejected `/passport/login` (non-zero code, so `data` is an error envelope not the encrypted
+     * payload), throw a diagnostic that names WHY the passport refused — the throttle (`26161`, "too
+     * frequent") vs a challenge it wants the client to satisfy. The passport marks a required captcha with
+     * a `captcha_id`/`item`; our headless client cannot answer one, so surfacing it distinguishes "wait
+     * out the rate-limit" from "a captcha is required — clear it in the app". No secrets are logged, only
+     * the code, message, and which challenge fields are present.
+     */
+    private assertLoginAccepted;
     /** Complete a `2fa` login with the code the passport sent. */
     submitVerifyCode(code: string): Promise<SolixLoginResult>;
     /**
      * One authenticated PLAIN read for both GET and POST endpoints (no per-request encryption; carries
      * the auth token + `gtoken` only). Routes through {@link send} so every read keeps the non-JSON guard.
+     *
+     * Self-heals a **displaced session**: Anker allows ~one session per account, so another login (the app,
+     * or a second client) invalidates this token and reads then fail with {@link SOLIX_TOKEN_KICKED_CODE}
+     * ("token does not exist because it was kicked out"). On that code this re-logs in once and retries, so
+     * a running client recovers on its own instead of failing every read until its session store is cleared.
      */
     private authed;
     /**
@@ -149,10 +163,27 @@ export declare class SolixClient {
      * beyond `device_sn`/`product_code` is optional on the record, so a caller reads them defensively.
      */
     getDevices(): Promise<SolixDeviceRecord[]>;
-    /** The account's sites (systems); devices are typically grouped under a site. */
-    getSites(): Promise<unknown[]>;
+    /**
+     * The account's sites (systems); devices are grouped under a site. Each record carries its
+     * `site_device_list` (the member devices), which {@link discoverSolixSites} resolves into a
+     * capability-driven `SolixSite`. Asserted to {@link SolixSiteRecord} at this trust boundary — and
+     * `site_id` (the one field the model layer keys a `SolixSite` on) is validated here, so a record the
+     * cloud returns without a usable id is dropped rather than surfacing a `SolixSite` with `id ===
+     * undefined`; every other field is optional and read defensively.
+     */
+    getSites(): Promise<SolixSiteRecord[]>;
     /** Per-user AWS-IoT MQTT credentials (cert/key/endpoint/thing) for the real-time device plane. */
     getUserMqttInfo(): Promise<SecureMqttCredentials>;
+    /**
+     * Read a site's "scene" snapshot — the app's dashboard read for a system, a plain authed read. Its
+     * battery detail (`solarbank_info.solarbank_list[]`) carries clean, correctly-named fields including
+     * `bat_temperature`, which the realtime `ff09` MQTT push does NOT reliably carry (the fast frame's BMS
+     * blob is empty, so the decoder withholds temperature). This is therefore a low-rate BACKSTOP for those
+     * gap fields — NOT the realtime source: live power/SOC still come from the MQTT push (which is what the
+     * app itself refreshes from every ~5 s; there is no clean-JSON scene PUSH). Verified live against the
+     * `ff09` floats — the two agree to the watt at the same instant.
+     */
+    getSiteScene(siteId: string): Promise<SolixSiteScene>;
     /**
      * The pairable-product catalog (categories → products). This is Anker's product registry, not the
      * account's devices — fetch it to label a discovered device's model code with a marketing name and
@@ -160,4 +191,79 @@ export declare class SolixClient {
      * baked-in table.
      */
     getProductCatalog(): Promise<SolixProductCategory[]>;
+    /**
+     * Write device attributes — a CONTROL write, e.g. the Solarbank ambient light
+     * `{ ambient_light_switch: 0 | 1 }` (0 = on, 1 = off). Unlike the plain authenticated reads, a write
+     * must be **encrypted + signed** with a freshly negotiated `algo_ecdh` key: the gateway accepts an
+     * unsigned write with `code 0` but the device never applies it. The token-bearing request also must
+     * NOT carry the device id (`openudid`), or the gateway answers `401 token error`. Both verified live
+     * on an AE103 (the LED-enable bit in the `ba` telemetry flips exactly as commanded).
+     */
+    setDeviceAttrs(deviceSn: string, attributes: Record<string, unknown>): Promise<void>;
+    /**
+     * A CONTROL write: `algo_ecdh`-encrypted + signed, token-bearing but WITHOUT `openudid`. Every device
+     * control the account performs (set_device_attrs, set_power_cutoff, …) goes through this — the gateway
+     * accepts an unsigned/plain write with `code 0` but the device never applies it, and adding `openudid`
+     * to the token-bearing request returns `401 token error`. Both verified live on an AE103.
+     */
+    private encryptedWrite;
+    /** Turn the Solarbank's ambient LED on/off — a confirmed `set_device_attrs` write. */
+    setAmbientLight(deviceSn: string, on: boolean): Promise<void>;
+    /**
+     * Read device attributes — a plain authenticated read (unlike the encrypted write). `attributes`
+     * names the keys to fetch (e.g. `["screen_off_time"]`); an empty list asks for the device's default
+     * set. Returns the gateway's attribute map as-is (values are device-typed — numbers, strings). Used
+     * to reflect a control's live state, e.g. the display/light off-timeout.
+     */
+    getDeviceAttrs(deviceSn: string, attributes?: string[]): Promise<Record<string, unknown>>;
+    /**
+     * Set the Solarbank display's screen-off timeout, in SECONDS (`screen_off_time`). The app's picker
+     * offers 10/20/30 s and 1/5/30 min; the LCD backlight — and with it the ambient LED that the screen
+     * gates — turns off after this idle period. This is the raw-seconds write; the caller maps its own UI
+     * options to seconds. The "Never" (always-on) sentinel is device-defined and NOT assumed here — pass
+     * the exact integer read back from {@link getDeviceAttrs} while the device is in that mode.
+     */
+    setScreenOffTime(deviceSn: string, seconds: number): Promise<void>;
+    /**
+     * Read the Solarbank's battery discharge-cutoff (minimum-SOC) options — a plain authed read.
+     * The gateway returns a preset list (`power_cutoff_data`): each entry is a selectable minimum
+     * state-of-charge `output_cutoff_data` (percent) with its `id` and `is_selected` flag. The caller
+     * presents these options and writes the chosen `id` back via {@link setPowerCutoff} — the values and
+     * ids come from the device, never assumed. `siteId` is optional (the device knows its own cutoff).
+     */
+    getPowerCutoff(deviceSn: string, siteId?: string): Promise<SolixPowerCutoffOption[]>;
+    /**
+     * Select the Solarbank's battery discharge-cutoff (minimum SOC) by option id — a control write.
+     * `cutoffDataId` MUST be an `id` returned by {@link getPowerCutoff} for this device (the preset the
+     * user picked), never a raw percentage; the gateway maps the id to its cutoff percent.
+     */
+    setPowerCutoff(deviceSn: string, cutoffDataId: number): Promise<void>;
+    /** The `param_type` under which the Solarbank's SOC-limit block lives (verified live on an AE103). */
+    private static readonly SOC_PARAM_TYPE;
+    /** `cmd` value that scopes the `site/*_site_device_param` family (from the app's request builder). */
+    private static readonly SITE_DEVICE_PARAM_CMD;
+    /**
+     * Read one of a site's "device param" blocks by `param_type` — a plain authenticated read whose
+     * `data.param_data` is itself a JSON STRING (the vendor double-encodes it). Returns the parsed inner
+     * object, or `{}` when the block is empty (the gateway answers `code 0` with an empty `param_data`
+     * for a `param_type` that does not apply to the site's hardware). The caller owns the inner shape.
+     */
+    private getSiteDeviceParam;
+    /**
+     * Read the Solarbank's battery SOC-limit settings (`param_type "27"`) — a plain authenticated read.
+     * Returns `undefined` when the site carries no SOC block (e.g. non-Solarbank hardware). The realtime
+     * `dischargeLowerLimit` also arrives on the MQTT `b5` telemetry blob; this is the authoritative,
+     * app-synced source (and the only source for `chargeUpperLimit` / `backupReserve`). Verified live
+     * against a known AE103 setting (discharge 20 / charge 80).
+     */
+    getSafetySocParams(siteId: string): Promise<SolixSocParams | undefined>;
+    /**
+     * Write the Solarbank's battery SOC limits — an `algo_ecdh`-encrypted + signed control write. This is
+     * **read-modify-write**: it first reads the current `param_type "27"` block and overlays only the
+     * fields the caller supplies, so changing the discharge limit alone never clobbers the charge limit,
+     * backup reserve, or calibration toggle. `changes` values are whole-percent integers. The full block
+     * (all five keys) is sent, matching the app's `SocSettingParam.toJson`. Throws if the site has no SOC
+     * block to modify. Returns the merged parameters that were written (for an immediate optimistic echo).
+     */
+    setSafetySocParams(siteId: string, changes: Partial<SolixSocParams>): Promise<SolixSocParams>;
 }

package/dist/transport/http/solix-constants.d.ts

@@ -26,4 +26,31 @@ export declare const SOLIX_ENDPOINTS: {
     readonly getUserMqttInfo: "/v1/openapi/devicemanage/get_user_mqtt_info";
     /** GET: the pairable-product catalog (categories → products), for labelling model codes. */
     readonly productCategories: "/power_service/v1/product_categories";
+    /** POST (encrypted+signed): write device attributes, e.g. `{ambient_light_switch: 0|1}`. */
+    readonly setDeviceAttrs: "/power_service/v1/app/device/set_device_attrs";
+    /** POST (plain authed): read device attributes, e.g. the display `screen_off_time` (seconds). */
+    readonly getDeviceAttrs: "/power_service/v1/app/device/get_device_attrs";
+    /** POST (plain authed): the battery discharge-cutoff (minimum-SOC) preset options. */
+    readonly getPowerCutoff: "/power_service/v1/app/compatible/get_power_cutoff";
+    /** POST (encrypted+signed): select the discharge-cutoff preset by `cutoff_data_id`. */
+    readonly setPowerCutoff: "/power_service/v1/app/compatible/set_power_cutoff";
+    /**
+     * POST (plain authed): the site "scene" snapshot — the same clean Solarbank/grid telemetry the app
+     * reads on load/refresh. Used as a low-rate BACKSTOP for the fields the realtime `ff09` push doesn't
+     * carry reliably (notably `bat_temperature`), NOT as the realtime source (that is the MQTT push).
+     */
+    readonly getSiteScene: "/power_service/v2/site/platform_get_site_scene";
+    /**
+     * POST (plain authed): read a site "device param" block by `param_type`. Body is
+     * `{ site_id, param_type, cmd: 246 }`; the response's `data.param_data` is a JSON STRING the caller
+     * parses. The Solarbank's SOC-limit settings live under `param_type "27"` (charge/discharge limits,
+     * backup reserve) — verified live on an AE103 (`"18"` returns empty for this device).
+     */
+    readonly getSiteDeviceParam: "/power_service/v1/site/get_site_device_param";
+    /**
+     * POST (encrypted+signed): write a site "device param" block. Body is
+     * `{ site_id, cmd: 246, param_type, param_data: <JSON string> }`. Used for the SOC-limit write
+     * (`param_type "27"`, `param_data` = the SocSettingParam map) — see {@link SolixClient.setSafetySocParams}.
+     */
+    readonly setSiteDeviceParam: "/power_service/v1/site/set_site_device_param";
 };

package/dist/transport/mqtt/solix-mqtt.d.ts

@@ -71,6 +71,51 @@ export declare const SOLIX_METER_FIELD_NAMES: Readonly<Record<number, string>>;
  * transport). Add a meter prefix to both.
  */
 export declare const SOLIX_METER_PRODUCT_PREFIXES: readonly string[];
+/**
+ * Product-code prefix of the gen-4 Solarbank (the `ats_ax170` family, e.g. `AE103` Solarbank 4 E5000
+ * Pro) whose ff09 tag layout {@link SOLIX_SOLARBANK_FIELD_NAMES} + the SOC/temperature extraction
+ * describe. Like the meter table this is family-specific — the SAME tag carries a different quantity on
+ * the meter (`0xac` is line voltage there, battery power here), so the Solarbank names are applied ONLY
+ * to a frame from this family. A product-code prefix used to pick a decode table, not a model import.
+ * `AE10` covers the AE10x gen-4 Solarbanks and does NOT match the meter (`AE1X0`, whose 4th char is `X`).
+ */
+export declare const SOLIX_SOLARBANK_PRODUCT_PREFIX = "AE10";
+/**
+ * Confirmed ff09 tag → field bindings for the gen-4 Solarbank (`ats_ax170`), correlated live against the
+ * app UI. Power values in watts; signed fields note their sign convention:
+ * - `0xac` battery power, SIGNED (+ charging / − discharging) — the measured net pack power.
+ * - `0xbc` charge power (0 unless charging); `0xad` discharge power (0 unless discharging).
+ * - `0xae` AC plug power, SIGNED (+ feeding the home / − drawing in to charge).
+ * - `0xaf` socket power — the unit's own on-board AC outlet (an appliance plugged into the Solarbank).
+ * - `0xc4` grid input power; `0xc5` home load power.
+ * SOC and temperature are NOT float channels — see {@link solixReadings}, which reads SOC from tag `0xa3`
+ * (a uint8) and temperature from the `0xa4` BMS status blob. The 4 PV-string channels (`0xc6`–`0xc9`),
+ * the AC currents (`0xb2`/`0xb3`) and export energy (`0xb4`) are not yet confirmed, so they stay raw
+ * `channel_<hex>` until a capture pins them.
+ */
+export declare const SOLIX_SOLARBANK_FIELD_NAMES: Readonly<Record<number, string>>;
+/**
+ * Confirmed `state_info` tag → field bindings for the gen-4 Solarbank. `state_info` is a SEPARATE push
+ * topic from `param_info` and, though it shares the ff09 framing, its tags carry SETTINGS/targets, NOT
+ * live measurements — so the SAME tag byte means something different here than in
+ * {@link SOLIX_SOLARBANK_FIELD_NAMES} (e.g. `0xab` is live PV power in param_info, the mode's AC-socket
+ * export limit here). Mapped by live observation against the app's SOC-setting screen; everything else
+ * stays raw `state_<hex>` until confirmed the same way.
+ */
+export declare const SOLIX_STATE_FIELD_NAMES: Readonly<Record<number, string>>;
+/**
+ * Decode a `state_info` ff09 frame to named + raw settings values. Skips the header tags (`< 0xa5`:
+ * request marker, serial, timestamps). Each settings tag is emitted under `state_<hex>` (a plain number
+ * so it's watchable in a consumer while more tags get mapped) AND, when confirmed, under its name from
+ * {@link SOLIX_STATE_FIELD_NAMES}. Value is read type-aware: `0x05` float32, `0x02` u16, `0x01` u8, and
+ * `0x03` the whole-number settings byte (`payload[1]`).
+ *
+ * The header cutoff is `0xa5` here, deliberately one lower than {@link solixReadings}' `0xa6` for
+ * `param_info`: the two frames are different layouts under the same ff09 framing — `state_info` carries
+ * a settings value at `0xa5` (SOC), where `param_info` has a header tag. The cutoffs are not meant to
+ * match; the spec pins `0xa5`'s treatment in each so they can't silently drift together.
+ */
+export declare function solixStateReadings(frame: SolixParamFrame): Record<string, number>;
 /** Interpret one TLV value as a telemetry channel (leading type byte + payload). */
 export declare function readSolixChannel(value: Buffer | undefined): SolixChannel | undefined;
 /**
@@ -86,10 +131,11 @@ export declare function decodeSolixParamFrame(buf: Buffer): SolixParamFrame | nu
  * carry the field count, the serial and the status, not measurements. A measurement channel is one whose
  * leading type byte is `0x05` (float32 LE over a 4-byte payload); any other type is a non-measurement
  * param and contributes nothing. Each measurement is emitted under `channel_<hex tag>`, and additionally
- * under its name when the tag has a confirmed one in {@link SOLIX_METER_FIELD_NAMES} AND `productCode` is
- * from the meter family (see {@link SOLIX_METER_PRODUCT_PREFIXES}) — so a non-meter device's tags stay
- * raw `channel_<hex>` rather than borrowing the meter's tag→name table. `productCode` is required (it
+ * under its name when the tag has a confirmed one AND `productCode` is from a known family — pass the
+ * telemetry topic's product code so a device outside the meter/Solarbank families keeps raw
+ * `channel_<hex>` rather than borrowing another family's tag→name table. `productCode` is required (it
  * comes straight from the telemetry topic); pass `""` for a frame of unknown origin and no names apply.
+ * Meter family: {@link SOLIX_METER_PRODUCT_PREFIXES}; Solarbank: {@link SOLIX_SOLARBANK_PRODUCT_PREFIX}.
  */
 export declare function solixReadings(frame: SolixParamFrame, productCode: string): Record<string, number>;
 /** A live telemetry sample emitted by {@link SolixMqtt} as a `reading` event. */
@@ -176,9 +222,14 @@ export declare class SolixMqtt extends EventEmitter {
      * Connect, subscribe to the device's telemetry (+ command-reply) topics, ARM realtime reporting, and
      * start the re-arm/heartbeat timer so telemetry keeps flowing without the app. Idempotent per device.
      *
-     * Subscribes ONLY to what the device sends — `param_info` plus the device and account command-reply
-     * channels — never the `…/req` channels, which are the app→device request side this arms on, and would
-     * echo its own publishes back.
+     * Subscribes to `param_info` (+ the device/account command-reply channels) AND the device's `…/req`
+     * channel. `…/req` is the app→device request side — the broker copies the APP's own publishes there to
+     * any co-subscriber, so watching it lets us read a control the app changed that the telemetry does NOT
+     * reflect: the Solarbank's ambient light and display timeout ride an `…/req` cmd-17 (`0x68`) command
+     * (tags `a4`/`a5`), and the `param_info` `ba` bit only tracks OUR `set_device_attrs` write, never the
+     * app's separate command path. `onMessage` filters these — our own arming/echoes carry no
+     * `a4`/`a5` — and turns an app command into a `reading` with the app-set state. A `…/req` grant denial
+     * is non-fatal (only `param_info` is required); we just won't see app-side changes.
      *
      * Throws when `param_info` was not granted. A scope-denied filter comes back as SUBACK_FAILURE rather
      * than an error (see `SecureMqtt.subscribe`), so an unusable subscription otherwise looks like
@@ -189,6 +240,14 @@ export declare class SolixMqtt extends EventEmitter {
     watch(device: SolixMqttDevice): Promise<void>;
     /** Tear down the connection and stop the re-arm timer. */
     close(): Promise<void>;
+    /**
+     * Set a Solarbank's display screen-off timeout — publishes the captured cmd-17 command (ff09 msgtype
+     * `0x68`, tag `a5 = [01, index]`) on the device's `…/req` channel via the same envelope the arming
+     * poll uses (`sign_code:1`, no per-message signature — which the device accepts for cmd 17). `index`
+     * is the 1-based dropdown position (10s=1, 20s=2, 30s=3, 1m=4, 5m=5, 30m=6); "Never" is a separate
+     * command not handled here. Fire-and-forget: the device does not ack on a subscribed channel.
+     */
+    setDisplayTimeout(device: SolixMqttDevice, index: number): Promise<void>;
     /**
      * Re-arm every watched device and send the site heartbeat. The device only pushes `param_info` while
      * a client keeps requesting it — this replays the app's `requestDeviceInfo` (cmd 17) + `power_site`
@@ -216,8 +275,25 @@ export declare class SolixMqtt extends EventEmitter {
      * Decode one inbound MQTT message envelope and emit a `reading` if it carries an ff09 param frame. The
      * product code and the fallback serial come from the topic (`dt/{app}/{pn}/{sn}/param_info`); the frame's
      * own `a2` field wins for the serial when it carries one.
+     *
+     * Serial resolution matters because NOT every frame carries it: the device-info frame (which alone
+     * carries SOC/temperature via tags a3/a4) has a 1-byte `a2` (a status, not a serial) and can arrive on
+     * a topic whose serial segment isn't the device serial either — leaving a `deviceSn` that matches no
+     * watched device, so a consumer keying on it would drop the reading (and its temperature). So when the
+     * resolved serial isn't a watched device, fall back to the single watched device of this product code.
      */
     private onMessage;
+    /**
+     * Turn an app→device cmd-17 (`0x68`) command seen on the `…/req` channel into a `reading` carrying the
+     * app-set control state, so a change made in the app reflects back. The Solarbank's ambient light and
+     * display timeout are set this way (byte-identical to what {@link setDisplayTimeout} publishes), and the
+     * broker copies the app's publish to us as a co-subscriber. Only `0x68` frames carrying `a4`/`a5` are
+     * emitted, so the arming polls (`0x40`/`0x57`) and our own echoes contribute nothing:
+     * - `a4 = [01, s]` → ambient light, INVERTED (`s` 0 = on) → `ambientLightOn` 1/0. The `ba` telemetry
+     *   bit only tracks our `set_device_attrs` write, so this is the ONLY read-back of an app light toggle.
+     * - `a5 = [01, i]` → display timeout, `i` = 1-based dropdown index → `displayTimeoutIndex`.
+     */
+    private handleCommand;
 }
 /**
  * Pull the ff09 binary frame out of a received message. Solix telemetry arrives as a `{head, payload}`
@@ -235,4 +311,11 @@ export declare function extractFf09Payload(raw: unknown): Buffer | null;
  * `fe` carries a fresh unix-timestamp nonce; the trailing byte is XOR of every preceding byte (the same
  * checksum the meter's telemetry frames use — verified to reproduce the captured frames exactly).
  */
+/**
+ * Build the display screen-off-timeout command frame (ff09 msgtype `0x68`, tag `a5 = [01, index]`),
+ * captured live from the app on `cmd/anker_power/<pc>/<sn>/req` (cmd 17). `index` is the 1-based
+ * position in the app dropdown `[10s,20s,30s,1m,5m,30m]` — live-confirmed 10s=1, 30s=3, 1m=4. "Never"
+ * is a separate command (not this one). Byte-identical to the captured frames modulo the index byte.
+ */
+export declare function buildDisplayTimeoutFrame(index: number): Buffer;
 export declare function buildFf09Request(variant: "info" | "realtime", atUnixSec?: number): Buffer;

package/dist/transport/mqtt/topics.d.ts

@@ -80,14 +80,24 @@ export interface ParsedTopic {
 export declare function parseSecureTopic(topic: string): ParsedTopic | undefined;
 /** The per-device Solix topics for `{appName, productCode, deviceSn}`. */
 export interface SolixDeviceTopics {
-    /** Telemetry the device pushes (SUBSCRIBE) — ff09 `param_info` frames. */
+    /** Telemetry the device pushes (SUBSCRIBE) — ff09 `param_info` frames (live measurements). */
     paramInfo: string;
+    /**
+     * Settings/state the device pushes (SUBSCRIBE) — ff09 `state_info` frames. Same ff09 framing as
+     * `param_info` but the TAGS carry SETTINGS/targets (mode export limit, SOC limits, max_load, toggles),
+     * NOT live measurements — so it needs its own tag→name table, not the param_info one.
+     */
+    stateInfo: string;
     /** This device's command replies (SUBSCRIBE). */
     cmdRes: string;
-    /** The device's requestDeviceInfo channel (PUBLISH only — the app arms reporting here). */
+    /**
+     * The device's requestDeviceInfo channel (cmd 17). PUBLISH to arm reporting; also SUBSCRIBE — the
+     * broker copies the APP's publishes here to any co-subscriber, which is the only way to observe a
+     * control the app changed that `param_info` does not reflect (ambient light, display timeout).
+     */
     req: string;
 }
-/** Build the per-device Solix topics. `param_info` is the telemetry we decode; `req` is publish-only. */
+/** Build the per-device Solix topics. `param_info` is the telemetry we decode; `req` is arm + read-back. */
 export declare function solixDeviceTopics(appName: string, productCode: string, deviceSn: string): SolixDeviceTopics;
 /** The per-account Solix topics keyed by `user_id`. */
 export interface SolixUserTopics {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mega-yfue/eufy-sdk",
-  "version": "0.2.0-beta.17",
+  "version": "0.2.0-beta.19",
   "description": "One typed TypeScript client for the Anker eufy v6 cloud — capability-driven devices, realtime events over P2P/MQTT/push, and live media",
   "license": "Apache-2.0",
   "author": "mega-yfue",