@mega-yfue/eufy-sdk 0.2.0-beta.16 → 0.2.0-beta.18

package/dist/index.js

@@ -2035,7 +2035,12 @@ function parseSecureTopic(topic) {
 function solixDeviceTopics(appName, productCode, deviceSn) {
   const dt = `dt/${appName}/${productCode}/${deviceSn}`;
   const cmd = `cmd/${appName}/${productCode}/${deviceSn}`;
-  return { paramInfo: `${dt}/param_info`, cmdRes: `${cmd}/app/res`, req: `${cmd}/req` };
+  return {
+    paramInfo: `${dt}/param_info`,
+    stateInfo: `${dt}/state_info`,
+    cmdRes: `${cmd}/app/res`,
+    req: `${cmd}/req`
+  };
 }
 function solixUserTopics(appName, userId) {
   return { cmdRes: `cmd/${appName}/${userId}/res`, powerSite: `dt/${appName}/${userId}/power_site` };
@@ -13631,11 +13636,7 @@ function inspectParams(rec, sn) {
 
 // dist/model/capabilities/solix.js
 var SOLIX_ENERGY_METER_MEMBERS = {
-  /**
-   * Line-1 voltage (V), ff09 tag `0xAC` — the ONE confirmed meter binding, matched against a live
-   * single-phase frame (a nominal mains voltage). Read-only; the evidence gate installs its getter only
-   * once a frame carrying `0xAC` has landed, so it is absent (not a fabricated `0`) until then.
-   */
+  /** Line-1 voltage (V), ff09 tag `0xAC` — confirmed live (a nominal mains voltage). */
   meterVoltageL1: {
     param: 172,
     type: "number",
@@ -13643,11 +13644,99 @@ var SOLIX_ENERGY_METER_MEMBERS = {
     unit: "V",
     provenance: "verified",
     description: "Meter line-1 voltage (V) \u2014 ff09 tag 0xAC, confirmed against a live single-phase frame."
+  },
+  /** Line-2 voltage (V), ff09 tag `0xAD` — the app's field; reads 0 until a multi-phase frame carries it. */
+  meterVoltageL2: {
+    param: 173,
+    type: "number",
+    kind: "scalar",
+    unit: "V",
+    provenance: "guessed",
+    description: "Meter line-2 voltage (V) \u2014 ff09 tag 0xAD; phase assignment inferred from block ordering (never observed non-zero), 0 on a single-phase install."
+  },
+  /** Line-3 voltage (V), ff09 tag `0xAE` — the app's field; reads 0 until a multi-phase frame carries it. */
+  meterVoltageL3: {
+    param: 174,
+    type: "number",
+    kind: "scalar",
+    unit: "V",
+    provenance: "guessed",
+    description: "Meter line-3 voltage (V) \u2014 ff09 tag 0xAE; phase assignment inferred from block ordering (never observed non-zero), 0 on a single-phase install."
+  },
+  /** Line-1 current (A), ff09 tag `0xAF` — confirmed live (the line's CT current). */
+  meterCurrentL1: {
+    param: 175,
+    type: "number",
+    kind: "scalar",
+    unit: "A",
+    provenance: "verified",
+    description: "Meter line-1 current (A) \u2014 ff09 tag 0xAF, confirmed against a live single-phase frame."
+  },
+  /** Line-2 current (A), ff09 tag `0xB0` — the app's field; reads 0 until a multi-phase frame carries it. */
+  meterCurrentL2: {
+    param: 176,
+    type: "number",
+    kind: "scalar",
+    unit: "A",
+    provenance: "guessed",
+    description: "Meter line-2 current (A) \u2014 ff09 tag 0xB0; phase assignment inferred from block ordering (never observed non-zero), 0 on a single-phase install."
+  },
+  /** Line-3 current (A), ff09 tag `0xB1` — the app's field; reads 0 until a multi-phase frame carries it. */
+  meterCurrentL3: {
+    param: 177,
+    type: "number",
+    kind: "scalar",
+    unit: "A",
+    provenance: "guessed",
+    description: "Meter line-3 current (A) \u2014 ff09 tag 0xB1; phase assignment inferred from block ordering (never observed non-zero), 0 on a single-phase install."
+  },
+  /** Line-1 active power (W), ff09 tag `0xA8` — confirmed live; negative on export. */
+  meterPowerL1: {
+    param: 168,
+    type: "number",
+    kind: "scalar",
+    unit: "W",
+    provenance: "verified",
+    description: "Meter line-1 active power (W) \u2014 ff09 tag 0xA8, confirmed live; negative on export."
+  },
+  /** Line-2 active power (W), ff09 tag `0xA9` — the app's field; reads 0 until a multi-phase frame carries it. */
+  meterPowerL2: {
+    param: 169,
+    type: "number",
+    kind: "scalar",
+    unit: "W",
+    provenance: "guessed",
+    description: "Meter line-2 active power (W) \u2014 ff09 tag 0xA9; phase assignment inferred from block ordering (never observed non-zero), 0 on a single-phase install."
+  },
+  /** Line-3 active power (W), ff09 tag `0xAA` — the app's field; reads 0 until a multi-phase frame carries it. */
+  meterPowerL3: {
+    param: 170,
+    type: "number",
+    kind: "scalar",
+    unit: "W",
+    provenance: "guessed",
+    description: "Meter line-3 active power (W) \u2014 ff09 tag 0xAA; phase assignment inferred from block ordering (never observed non-zero), 0 on a single-phase install."
+  },
+  /** Aggregate active power (W), ff09 tag `0xAB` — confirmed live; equals line-1 on a single phase. */
+  meterPowerTotal: {
+    param: 171,
+    type: "number",
+    kind: "scalar",
+    unit: "W",
+    provenance: "verified",
+    description: "Meter total active power (W) \u2014 ff09 tag 0xAB, confirmed live; equals L1 on one phase."
   }
 };
 var CATEGORY_CAPABILITIES = {
   "Portable Power Station": ["battery", "acOutput", "solarInput"],
-  "Plug-in Home Battery": ["battery", "solarInput", "acOutput", "energyMeter"],
+  /**
+   * NOT `energyMeter`: a home battery measures its own grid/PV/output power, but that is a different
+   * ff09 tag family than the AE1X0 Smart Meter's — the `energyMeter` members are AE1X0-specific, so a
+   * Solarbank frame decoded through them mislabels (tag `0xac` is power on a Solarbank, voltage on the
+   * meter — enforced by the meter-family gate in {@link SOLIX_METER_MODELS} / the transport decoder,
+   * see PR #186). `energyMeter` is model-detected for the meter, not category-detected.
+   */
+  "Plug-in Home Battery": ["battery", "solarInput", "acOutput"],
   "Powered Cooler": ["battery", "cooler"],
   "Power Bank": ["battery"],
   "Smart EV Charger": ["evCharger"],
@@ -13655,7 +13744,7 @@ var CATEGORY_CAPABILITIES = {
   Accessory: []
 };
 var SOLIX_METER_MODELS = ["AE1X0"];
-var SOLARBANK_MODELS = ["A1790", "A17C"];
+var SOLARBANK_MODELS = ["A1790", "A17C", "AE10"];
 function detectSolixCapabilities(rec, category) {
   const caps = /* @__PURE__ */ new Set(["identity"]);
   if (rec.device_sw_version)
@@ -13678,7 +13767,7 @@ function buildModelIndex(categories) {
   const index = /* @__PURE__ */ new Map();
   for (const category of categories) {
     for (const product of category.products ?? []) {
-      const entry = { name: product.name, category: category.name };
+      const entry = { name: product.name, category: category.name.trim() };
       if (product.product_code)
         index.set(product.product_code, entry);
       for (const variant of product.p_codes ?? []) {
@@ -13691,6 +13780,26 @@ function buildModelIndex(categories) {
   return index;
 }
 
+// dist/model/solix-family.js
+var CATEGORY_FAMILY = {
+  "Portable Power Station": "powerStation",
+  "Power Bank": "powerBank",
+  "Powered Cooler": "cooler",
+  "Smart EV Charger": "evCharger",
+  Charger: "charger"
+};
+var hasPrefix = (code, prefixes) => !!code && prefixes.some((p) => code.startsWith(p));
+var isSolixSolarbank = (input) => hasPrefix(input.product_code, SOLARBANK_MODELS) || input.category === "Plug-in Home Battery";
+var isSolixSmartMeter = (input) => hasPrefix(input.product_code, SOLIX_METER_MODELS);
+var isSolixPowerStation = (input) => input.category === "Portable Power Station";
+function solixProductFamily(input) {
+  if (isSolixSmartMeter(input))
+    return "smartMeter";
+  if (isSolixSolarbank(input))
+    return "solarbank";
+  return (input.category ? CATEGORY_FAMILY[input.category] : void 0) ?? "unknown";
+}
+
 // dist/model/solix-device.js
 var READ_ONLY_SINK = { dispatch: async () => {
 } };
@@ -13710,10 +13819,19 @@ var SolixDevice = class {
       serial: record.device_sn,
       productCode: record.product_code,
       name: label?.name ?? record.alias_name ?? record.device_name ?? record.product_code,
-      category: label?.category
+      category: label?.category,
+      family: solixProductFamily({ product_code: record.product_code, category: label?.category })
     };
     this.caps = detectSolixCapabilities(record, this.identity_.category);
   }
+  /**
+   * 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() {
+    return this.identity_.family;
+  }
   /** All capabilities this device carries. */
   get capabilities() {
     return [...this.caps];
@@ -13789,12 +13907,101 @@ var SolixDevice = class {
     return tags;
   }
 };
+function resolveSolixCatalog(client, opts) {
+  return opts.catalog ? Promise.resolve(opts.catalog) : client.getProductCatalog().catch(() => []);
+}
 async function discoverSolixDevices(client, opts = {}) {
-  const [records, catalog] = await Promise.all([
+  const [records, catalog] = await Promise.all([client.getDevices(), resolveSolixCatalog(client, opts)]);
+  return records.map((r) => new SolixDevice(r, { catalog }));
+}
+function sceneNum(v) {
+  if (typeof v === "number")
+    return Number.isFinite(v) ? v : void 0;
+  if (typeof v === "string" && v.trim() !== "") {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : void 0;
+  }
+  return void 0;
+}
+function solarbankSceneReadings(scene) {
+  const list = scene.solarbank_info?.solarbank_list ?? [];
+  const out = [];
+  for (const sb of list) {
+    const deviceSn = typeof sb.device_sn === "string" ? sb.device_sn : void 0;
+    if (!deviceSn)
+      continue;
+    const values = {};
+    const temp = sceneNum(sb.bat_temperature);
+    if (temp !== void 0)
+      values.batteryTemperature = temp;
+    const soc = sceneNum(sb.bat_soc);
+    if (soc !== void 0)
+      values.batterySoc = soc;
+    if (Object.keys(values).length > 0)
+      out.push({ deviceSn, values });
+  }
+  return out;
+}
+
+// dist/model/solix-site.js
+var SolixSite = class {
+  id;
+  /** Friendly site name (e.g. "My Home"), or the site id when the record carries none. */
+  name;
+  /** Anker's site-type discriminator (e.g. 20 for a Solarbank-anchored home system), when present. */
+  powerSiteType;
+  record;
+  devices;
+  constructor(record, devices) {
+    this.record = record;
+    this.id = record.site_id;
+    this.name = record.site_name || record.site_id;
+    this.powerSiteType = record.power_site_type;
+    this.devices = devices;
+  }
+  /** The member device with this serial, if it belongs to the site. */
+  device(serial) {
+    return this.devices.find((d) => d.serial === serial);
+  }
+  /** Member devices of a given product {@link SolixProductFamily} — the grouping accessor. */
+  withFamily(family) {
+    return this.devices.filter((d) => d.family === family);
+  }
+  /** Member devices that carry a given capability (e.g. every `battery` in the system). */
+  withCapability(capability) {
+    return this.devices.filter((d) => d.has(capability));
+  }
+  /** The Solarbank / plug-in home-battery members of the system. */
+  solarbanks() {
+    return this.withFamily("solarbank");
+  }
+  /** The smart-meter (grid-CT) members of the system. */
+  smartMeters() {
+    return this.withFamily("smartMeter");
+  }
+  /** The portable power-station members of the system. */
+  powerStations() {
+    return this.withFamily("powerStation");
+  }
+};
+async function discoverSolixSites(client, opts = {}) {
+  const [sites, records, catalog] = await Promise.all([
+    client.getSites(),
     client.getDevices(),
-    opts.catalog ? Promise.resolve(opts.catalog) : client.getProductCatalog().catch(() => [])
+    resolveSolixCatalog(client, opts)
   ]);
-  return records.map((r) => new SolixDevice(r, { catalog }));
+  const bySerial = new Map(records.map((r) => [r.device_sn, r]));
+  return sites.map((site) => {
+    const members = (site.site_device_list ?? []).map((entry) => {
+      const record = bySerial.get(entry.device_sn) ?? {
+        device_sn: entry.device_sn,
+        product_code: entry.device_model,
+        device_name: entry.device_name
+      };
+      return new SolixDevice(record, { catalog });
+    });
+    return new SolixSite(site, members);
+  });
 }
 
 // dist/client/map-channels.js
@@ -26289,15 +26496,43 @@ var SOLIX_ENDPOINTS = {
   /** Per-user AWS-IoT MQTT credentials (cert/key/endpoint/thing) for the real-time device plane. */
   getUserMqttInfo: "/v1/openapi/devicemanage/get_user_mqtt_info",
   /** GET: the pairable-product catalog (categories → products), for labelling model codes. */
-  productCategories: "/power_service/v1/product_categories"
+  productCategories: "/power_service/v1/product_categories",
+  /** POST (encrypted+signed): write device attributes, e.g. `{ambient_light_switch: 0|1}`. */
+  setDeviceAttrs: "/power_service/v1/app/device/set_device_attrs",
+  /** POST (plain authed): read device attributes, e.g. the display `screen_off_time` (seconds). */
+  getDeviceAttrs: "/power_service/v1/app/device/get_device_attrs",
+  /** POST (plain authed): the battery discharge-cutoff (minimum-SOC) preset options. */
+  getPowerCutoff: "/power_service/v1/app/compatible/get_power_cutoff",
+  /** POST (encrypted+signed): select the discharge-cutoff preset by `cutoff_data_id`. */
+  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).
+   */
+  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).
+   */
+  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}.
+   */
+  setSiteDeviceParam: "/power_service/v1/site/set_site_device_param"
 };
 
 // dist/transport/http/solix-client.js
 function solixSessionFresh(s) {
   return !!s?.authToken && tokenNotExpired(s.tokenExpiresAt);
 }
+var SOLIX_TOKEN_KICKED_CODE = 26084;
 var uuidFromHex = (hex) => `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
-var SolixClient = class {
+var SolixClient = class _SolixClient {
   email;
   password;
   country;
@@ -26475,8 +26710,34 @@ var SolixClient = class {
     await this.estimateHost();
     const kx = await this.keyExchange();
     const env = await this.postLogin(kx);
+    this.assertLoginAccepted(env);
     return this.classifyLogin(this.decryptLogin(env, kx), false);
   }
+  /**
+   * 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.
+   */
+  assertLoginAccepted(env) {
+    if (env.code === 0)
+      return;
+    const d = env.data ?? {};
+    const hints = [];
+    if (typeof d === "object" && d) {
+      if ("captcha_id" in d && d.captcha_id)
+        hints.push("captcha_id present (captcha required)");
+      if ("item" in d && d.item)
+        hints.push(`item=${String(d.item).slice(0, 40)}`);
+      const keys = Object.keys(d);
+      if (keys.length && hints.length === 0)
+        hints.push(`data keys: ${keys.join(",")}`);
+    }
+    const detail = hints.length ? ` [${hints.join("; ")}]` : "";
+    throw new Error(`Solix login (${env.code}): ${env.msg}${detail}`);
+  }
   /** Complete a `2fa` login with the code the passport sent. */
   async submitVerifyCode(code) {
     if (!this.pending2fa)
@@ -26488,14 +26749,26 @@ var SolixClient = class {
   /**
    * 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.
    */
-  async authed(method2, path, body) {
+  async authed(method2, path, body, reauthed = false) {
     if (!this.session_)
       throw new Error("not authenticated \u2014 call login() first");
     const env = await this.send(method2, this.apiHost, path, this.baseHeaders({ gtoken: this.session_.gtoken, "x-auth-token": this.session_.authToken }), body ? JSON.stringify(body) : void 0);
-    if (env.code !== 0)
-      throw new Error(`Solix ${path} failed (${env.code}): ${env.msg}`);
-    return env.data ?? null;
+    if (env.code === 0)
+      return env.data ?? null;
+    if (env.code === SOLIX_TOKEN_KICKED_CODE && !reauthed) {
+      this.session_ = void 0;
+      const r = await this.login();
+      if (r.status !== "ok")
+        throw new Error(`Solix ${path}: session was kicked and re-login did not complete (${r.status})`);
+      return this.authed(method2, path, body, true);
+    }
+    throw new Error(`Solix ${path} failed (${env.code}): ${env.msg}`);
   }
   /**
    * The account's bound Solix devices (flat list; may be empty when devices live under sites). The
@@ -26506,15 +26779,35 @@ var SolixClient = class {
     const data = await this.authed("POST", SOLIX_ENDPOINTS.getRelateAndBindDevices, {});
     return Array.isArray(data) ? data : data?.data ?? [];
   }
-  /** The account's sites (systems); devices are typically grouped under a site. */
+  /**
+   * 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.
+   */
   async getSites() {
     const data = await this.authed("POST", SOLIX_ENDPOINTS.getSiteList, {});
-    return data?.site_list ?? [];
+    const list = data?.site_list ?? [];
+    return list.filter((s) => typeof s?.site_id === "string" && s.site_id.length > 0);
   }
   /** Per-user AWS-IoT MQTT credentials (cert/key/endpoint/thing) for the real-time device plane. */
   async getUserMqttInfo() {
     return this.authed("POST", SOLIX_ENDPOINTS.getUserMqttInfo, {});
   }
+  /**
+   * 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.
+   */
+  async getSiteScene(siteId) {
+    return this.authed("POST", SOLIX_ENDPOINTS.getSiteScene, { site_id: siteId });
+  }
   /**
    * 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
@@ -26524,13 +26817,236 @@ var SolixClient = class {
   async getProductCatalog() {
     return await this.authed("GET", SOLIX_ENDPOINTS.productCategories) ?? [];
   }
+  /**
+   * 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).
+   */
+  async setDeviceAttrs(deviceSn, attributes) {
+    await this.encryptedWrite(SOLIX_ENDPOINTS.setDeviceAttrs, "set_device_attrs", {
+      device_sn: deviceSn,
+      attributes
+    });
+  }
+  /**
+   * 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.
+   */
+  async encryptedWrite(path, label, payload) {
+    if (!this.session_)
+      throw new Error("not authenticated \u2014 call login() first");
+    const kx = await this.keyExchange();
+    const encBody = encryptBody(JSON.stringify(payload), kx.shareKey);
+    const ts = nowSec();
+    const once = genId();
+    const env = await this.post(this.apiHost, path, encBody, this.baseHeaders({
+      "x-encryption-info": "algo_ecdh",
+      "x-key-ident": kx.keyIdent,
+      "x-request-ts": ts,
+      "x-request-once": once,
+      "x-signature": signRequest(kx.shareKey, ts, once, encBody),
+      "x-auth-token": this.session_.authToken,
+      gtoken: this.session_.gtoken
+    }));
+    if (env.code !== 0)
+      throw new Error(`Solix ${label} failed (${env.code}): ${env.msg}`);
+  }
+  /** Turn the Solarbank's ambient LED on/off — a confirmed `set_device_attrs` write. */
+  async setAmbientLight(deviceSn, on) {
+    await this.setDeviceAttrs(deviceSn, { ambient_light_switch: on ? 0 : 1 });
+  }
+  /**
+   * 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.
+   */
+  async getDeviceAttrs(deviceSn, attributes = []) {
+    const data = await this.authed("POST", SOLIX_ENDPOINTS.getDeviceAttrs, { device_sn: deviceSn, attributes });
+    if (data && typeof data === "object" && "attributes" in data && data.attributes) {
+      return data.attributes;
+    }
+    return data ?? {};
+  }
+  /**
+   * 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.
+   */
+  async setScreenOffTime(deviceSn, seconds) {
+    await this.setDeviceAttrs(deviceSn, { screen_off_time: seconds });
+  }
+  /**
+   * 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).
+   */
+  async getPowerCutoff(deviceSn, siteId = "") {
+    const data = await this.authed("POST", SOLIX_ENDPOINTS.getPowerCutoff, { site_id: siteId, device_sn: deviceSn });
+    return data?.power_cutoff_data ?? [];
+  }
+  /**
+   * 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.
+   */
+  async setPowerCutoff(deviceSn, cutoffDataId) {
+    await this.encryptedWrite(SOLIX_ENDPOINTS.setPowerCutoff, "set_power_cutoff", {
+      device_sn: deviceSn,
+      cutoff_data_id: cutoffDataId
+    });
+  }
+  /** The `param_type` under which the Solarbank's SOC-limit block lives (verified live on an AE103). */
+  static SOC_PARAM_TYPE = "27";
+  /** `cmd` value that scopes the `site/*_site_device_param` family (from the app's request builder). */
+  static SITE_DEVICE_PARAM_CMD = 246;
+  /**
+   * 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.
+   */
+  async getSiteDeviceParam(siteId, paramType) {
+    const data = await this.authed("POST", SOLIX_ENDPOINTS.getSiteDeviceParam, {
+      site_id: siteId,
+      param_type: paramType,
+      cmd: _SolixClient.SITE_DEVICE_PARAM_CMD
+    });
+    const raw = data?.param_data;
+    if (!raw)
+      return {};
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return {};
+    }
+  }
+  /**
+   * 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).
+   */
+  async getSafetySocParams(siteId) {
+    const p = await this.getSiteDeviceParam(siteId, _SolixClient.SOC_PARAM_TYPE);
+    if (typeof p.charge_upper_limit !== "number" || typeof p.discharge_lower_limit !== "number") {
+      return void 0;
+    }
+    return {
+      chargeUpperLimit: p.charge_upper_limit,
+      dischargeLowerLimit: p.discharge_lower_limit,
+      backupReserve: typeof p.backup_reserve === "number" ? p.backup_reserve : 0,
+      backupReserveSwitch: typeof p.backup_reserve_switch === "number" ? p.backup_reserve_switch : 0,
+      socCalibrationEnable: typeof p.soc_calibration_enable === "number" ? p.soc_calibration_enable : 0
+    };
+  }
+  /**
+   * 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).
+   */
+  async setSafetySocParams(siteId, changes) {
+    const current = await this.getSafetySocParams(siteId);
+    if (!current)
+      throw new Error(`Solix set SOC params: site has no param_type 27 block`);
+    const merged = { ...current, ...changes };
+    await this.encryptedWrite(SOLIX_ENDPOINTS.setSiteDeviceParam, "set_site_device_param", {
+      site_id: siteId,
+      cmd: _SolixClient.SITE_DEVICE_PARAM_CMD,
+      param_type: _SolixClient.SOC_PARAM_TYPE,
+      param_data: JSON.stringify({
+        charge_upper_limit: merged.chargeUpperLimit,
+        discharge_lower_limit: merged.dischargeLowerLimit,
+        backup_reserve_switch: merged.backupReserveSwitch,
+        backup_reserve: merged.backupReserve,
+        soc_calibration_enable: merged.socCalibrationEnable
+      })
+    });
+    return merged;
+  }
 };
 
 // dist/transport/mqtt/solix-mqtt.js
 import { EventEmitter as EventEmitter10 } from "node:events";
 var SOLIX_METER_FIELD_NAMES = {
-  172: "meterVoltageL1"
+  168: "meterPowerL1",
+  169: "meterPowerL2",
+  170: "meterPowerL3",
+  171: "meterPowerTotal",
+  172: "meterVoltageL1",
+  173: "meterVoltageL2",
+  174: "meterVoltageL3",
+  175: "meterCurrentL1",
+  176: "meterCurrentL2",
+  177: "meterCurrentL3",
+  179: "meterImportEnergy",
+  180: "meterExportEnergy"
+};
+var SOLIX_METER_PRODUCT_PREFIXES = ["AE1X0"];
+var SOLIX_SOLARBANK_PRODUCT_PREFIX = "AE10";
+var SOLIX_SOLARBANK_FIELD_NAMES = {
+  171: "photovoltaicPower",
+  // total PV input across the strings
+  172: "batteryPower",
+  188: "chargePower",
+  173: "dischargePower",
+  174: "acPlugPower",
+  175: "socketPower",
+  // the unit's own on-board AC socket (an appliance plugged into the Solarbank)
+  196: "gridInputPower",
+  197: "homeLoadPower",
+  198: "pv1Power",
+  // the four PV-string inputs (0 when a string is unused / dark)
+  199: "pv2Power",
+  200: "pv3Power",
+  201: "pv4Power"
 };
+var SOLIX_STATE_FIELD_NAMES = {
+  169: "mode",
+  // current operating (EMS) mode (1 custom, 2 self-consumption, 4 rapid charge, 7 smart, 8 dynamic tariff)
+  170: "maxLoad"
+  // configured max home load (W) — matches get_site_device_param max_load
+  // NOTE `0xab` is grid-in/out-related power but its exact meaning is not yet pinned, so it stays raw
+  // `state_ab` (a diagnostic a consumer can watch) rather than being asserted under a guessed name.
+};
+function solixStateReadings(frame) {
+  const out = {};
+  for (const [tag2, value] of frame.fields) {
+    if (tag2 < 165 || !value || value.length < 2)
+      continue;
+    const type = value[0];
+    const pl = value.subarray(1);
+    let num2;
+    if (type === 5 && pl.length >= 4)
+      num2 = pl.readFloatLE(0);
+    else if (type === 2 && pl.length >= 2)
+      num2 = pl.readUInt16LE(0);
+    else if (type === 1 && pl.length >= 1)
+      num2 = pl[0];
+    else if (type === 3 && pl.length >= 2)
+      num2 = pl[1];
+    if (num2 === void 0)
+      continue;
+    out[`state_${tag2.toString(16)}`] = num2;
+    const name = SOLIX_STATE_FIELD_NAMES[tag2];
+    if (name)
+      out[name] = num2;
+  }
+  return out;
+}
 function readSolixChannel(value) {
   if (!value || value.length < 1)
     return void 0;
@@ -26564,8 +27080,11 @@ function decodeSolixParamFrame(buf) {
     deviceSn = a2.subarray(1).toString("latin1").replace(/\0+$/, "") || void 0;
   return { deviceSn, fields };
 }
-function solixReadings(frame) {
+function solixReadings(frame, productCode) {
   const out = {};
+  const isMeter = SOLIX_METER_PRODUCT_PREFIXES.some((p) => productCode.startsWith(p));
+  const isSolarbank = productCode.startsWith(SOLIX_SOLARBANK_PRODUCT_PREFIX);
+  const floatNames = isMeter ? SOLIX_METER_FIELD_NAMES : isSolarbank ? SOLIX_SOLARBANK_FIELD_NAMES : void 0;
   for (const [tag2, value] of frame.fields) {
     if (tag2 < 166)
       continue;
@@ -26573,12 +27092,30 @@ function solixReadings(frame) {
     if (ch?.type !== 5 || ch.float === void 0)
       continue;
     out[`channel_${tag2.toString(16)}`] = ch.float;
-    const name = SOLIX_METER_FIELD_NAMES[tag2];
+    const name = floatNames?.[tag2];
     if (name)
       out[name] = ch.float;
   }
+  if (isSolarbank)
+    addSolarbankScalars(frame, out);
   return out;
 }
+function addSolarbankScalars(frame, out) {
+  const a3 = frame.fields.get(163);
+  const soc = a3 && a3.length >= 2 ? a3[1] : void 0;
+  if (soc !== void 0) {
+    out.batterySoc = soc;
+    const body = frame.fields.get(164)?.subarray(1);
+    if (body && body.length >= 8 && body[body.length - 6] === soc) {
+      out.batteryTemperature = body[body.length - 8];
+    }
+  }
+  const b5 = frame.fields.get(181);
+  if (b5 && b5[0] === 4 && b5.length === 4) {
+    out.dischargeLimit = b5[1];
+    out.chargeLimit = b5[3];
+  }
+}
 var SolixMqtt = class extends EventEmitter10 {
   transport;
   appName;
@@ -26622,9 +27159,14 @@ var SolixMqtt = class extends EventEmitter10 {
    * 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
@@ -26637,7 +27179,9 @@ var SolixMqtt = class extends EventEmitter10 {
     const topics = solixDeviceTopics(this.appName, device.product_code, device.device_sn);
     const granted = await this.transport.subscribe([
       topics.paramInfo,
+      topics.stateInfo,
       topics.cmdRes,
+      topics.req,
       ...this.userId ? [solixUserTopics(this.appName, this.userId).cmdRes] : []
     ]);
     if (!granted.includes(topics.paramInfo)) {
@@ -26662,6 +27206,19 @@ var SolixMqtt = class extends EventEmitter10 {
     this.watched.clear();
     await this.transport.disconnect();
   }
+  /**
+   * 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.
+   */
+  async setDisplayTimeout(device, index) {
+    const topic = solixDeviceTopics(this.appName, device.product_code, device.device_sn).req;
+    const body = this.commandEnvelope(device, buildDisplayTimeoutFrame(index), {});
+    await this.transport.publish(topic, body, { qos: 1 });
+    this.logger?.debug?.(`[solix] display timeout set index=${index} on ${device.device_sn}`);
+  }
   /**
    * 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`
@@ -26745,24 +27302,74 @@ var SolixMqtt = class extends EventEmitter10 {
    * 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.
    */
   onMessage(msg) {
     const topic = msg.topic ?? "";
     const buf = extractFf09Payload(msg.raw);
     if (!buf)
       return;
+    if (topic.endsWith("/req")) {
+      this.handleCommand(topic, buf);
+      return;
+    }
     const frame = decodeSolixParamFrame(buf);
     if (!frame)
       return;
     const parts = topic.split("/");
-    const reading = {
-      deviceSn: frame.deviceSn ?? parts[3] ?? "",
-      productCode: parts[2] ?? "",
-      topic,
-      frame,
-      values: solixReadings(frame)
-    };
-    this.emit("reading", reading);
+    const productCode = parts[2] ?? "";
+    let deviceSn = frame.deviceSn ?? parts[3] ?? "";
+    if (!this.watched.has(deviceSn)) {
+      const ofProduct = [...this.watched.values()].filter((d) => d.product_code === productCode);
+      if (ofProduct.length === 1)
+        deviceSn = ofProduct[0].device_sn;
+    }
+    const values = topic.endsWith("/state_info") ? solixStateReadings(frame) : (
+      // Pass the product code so meter tag→name binding is applied only to a meter frame; a Solarbank's
+      // tags stay raw channel_<hex> (the model names them per capability) rather than being mislabelled.
+      solixReadings(frame, productCode)
+    );
+    this.emit("reading", { deviceSn, productCode, topic, frame, values });
+  }
+  /**
+   * 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`.
+   */
+  handleCommand(topic, buf) {
+    if (buf.length < 10 || buf[8] !== 104)
+      return;
+    const frame = decodeSolixParamFrame(buf);
+    if (!frame)
+      return;
+    const values = {};
+    const a4 = frame.fields.get(164);
+    if (a4 && a4.length >= 2)
+      values.ambientLightOn = a4[1] === 0 ? 1 : 0;
+    const a5 = frame.fields.get(165);
+    if (a5 && a5.length >= 2)
+      values.displayTimeoutIndex = a5[1];
+    if (Object.keys(values).length === 0)
+      return;
+    const parts = topic.split("/");
+    const productCode = parts[2] ?? "";
+    let deviceSn = frame.deviceSn ?? parts[3] ?? "";
+    if (!this.watched.has(deviceSn)) {
+      const ofProduct = [...this.watched.values()].filter((d) => d.product_code === productCode);
+      if (ofProduct.length === 1)
+        deviceSn = ofProduct[0].device_sn;
+    }
+    this.emit("reading", { deviceSn, productCode, topic, frame, values });
   }
 };
 function extractFf09Payload(raw) {
@@ -26786,6 +27393,19 @@ function extractFf09Payload(raw) {
   const buf = Buffer.from(data, "base64");
   return buf.length ? buf : null;
 }
+function buildDisplayTimeoutFrame(index) {
+  const body = Buffer.from([3, 0, 15, 0, 104, 161, 1, 34, 165, 2, 1, index & 255]);
+  const frame = Buffer.alloc(body.length + 5);
+  frame[0] = 255;
+  frame[1] = 9;
+  frame.writeUInt16LE(frame.length, 2);
+  body.copy(frame, 4);
+  let xor = 0;
+  for (let i = 0; i < frame.length - 1; i++)
+    xor ^= frame[i];
+  frame[frame.length - 1] = xor;
+  return frame;
+}
 function buildFf09Request(variant, atUnixSec) {
   const ts = Buffer.alloc(4);
   ts.writeUInt32LE((atUnixSec ?? Math.floor(Date.now() / 1e3)) >>> 0);
@@ -26979,6 +27599,7 @@ export {
   SolixClient,
   SolixDevice,
   SolixMqtt,
+  SolixSite,
   StateConvergenceError,
   StationKeyUnavailableError,
   StationUnreachableError,
@@ -27051,6 +27672,7 @@ export {
   detectionName,
   discoverReachableInstance,
   discoverSolixDevices,
+  discoverSolixSites,
   encodeAiDetectType,
   encodeVarint,
   encryptBody,
@@ -27079,6 +27701,9 @@ export {
   isNotAuthorized,
   isPrivateIpv4,
   isSessionValid,
+  isSolixPowerStation,
+  isSolixSmartMeter,
+  isSolixSolarbank,
   isV1Image,
   isV2Image,
   jpegGeometry,
@@ -27133,7 +27758,9 @@ export {
   secureTopic,
   signKey,
   signRequest,
+  solarbankSceneReadings,
   solixDeviceTopics,
+  solixProductFamily,
   solixUserTopics,
   structuralEqual,
   subscribeTopics,