@mega-yfue/eufy-sdk 0.2.0-beta.27 → 0.2.0-beta.29

package/dist/client/device-registry.d.ts

@@ -1,13 +1,3 @@
-/**
- * The station a device's traffic belongs to, from its cloud record and its own serial.
- *
- * `parent_sn` carries the parent on a HomeBase-attached device. `station_sn` is frequently absent there —
- * empty on every attached sensor of a T8010 — and serves only as a fallback. An empty string states no
- * station.
- *
- * A device naming no parent answers its own serial, so every device has a station.
- */
-export declare function resolvedStationSn(raw: Record<string, unknown>, sn: string): string;
 /**
  * DeviceRegistry — the device list/record/capability-resolution collaborator behind {@link EufyMega}.
  *
@@ -85,6 +75,9 @@ export declare class DeviceRegistry {
     private devices;
     /** Per-(station, channel) capability cache for {@link capabilitiesForFrame}; `null` = negative hit. */
     private readonly frameCapsCache;
+    /** {@link stationChannels} of {@link channelMapFor}, the roster it was computed over. */
+    private channelMap;
+    private channelMapFor?;
     /**
      * Serials whose per-device param overlay has been refused. The call is owner-gated, so on a shared or
      * member account it fails for the whole life of the client — retrying it every refresh spends a request
@@ -291,33 +284,26 @@ export declare class DeviceRegistry {
      * hub would emit indistinguishable events. The facade enriches the payload with this.
      */
     serialForFrame(stationSn: string, channel: number): string | undefined;
-    /**
-     * The parent station a device's frames arrive under.
-     *
-     * `parent_sn` on the cloud record is the field that is actually populated for a HomeBase-attached
-     * device — `stationSn` is frequently absent (observed empty on every attached sensor of a T8010),
-     * so keying on it alone silently resolves an attached device to ITSELF and no frame ever matches.
-     * Mirrors the router's own session-keying precedence, which is the source of truth for which
-     * station a device's traffic belongs to. Answering the device's OWN serial is what "stands alone"
-     * means, so this is also the topology signal `record()`/`capsOf` hand the resolver.
-     */
-    private stationOf;
     /**
      * The device a `(station, channel)` pair refers to — a station fans out to attached devices by
      * `device_channel`, while a standalone device is its own station at channel 0.
      *
-     * A device claims a channel only when its record actually STATES one. Treating a missing
-     * `device_channel` as 0 turns every such device into a rival claimant for channel 0, where a
-     * station legitimately has an attached device already, and the winner is then decided by cloud list
-     * order — so the same frame resolves to different devices across refreshes. The resolved serial now
-     * decides where realtime state is written, not just which decoders may run, so an ambiguous answer
+     * A device claims a channel only when its record actually STATES one that no other device attached to
+     * the same station also states ({@link stationChannels}). Treating a missing `device_channel` as 0, or
+     * letting two claimants of one channel both hold it, leaves the winner to cloud list order — which a
+     * partial refresh reorders — so the same frame resolves to different devices across refreshes. The resolved
+     * serial decides where realtime state is written, not just which decoders may run, so an ambiguous answer
      * writes one device's params onto another.
      *
      * An attached device that names the channel wins over the station itself, which is what a station
-     * fanning traffic out by channel means; the station answers for channel 0 only when nothing is
-     * attached there, which is also the standalone case (a device is its own station).
+     * fanning traffic out by channel means. A channel two attached devices both state belongs to one of them,
+     * which cannot be told apart, so it answers nothing rather than the station. The station answers for
+     * channel 0 only when nothing attached states it, which is also the standalone case (a device is its own
+     * station).
      */
     private deviceForFrame;
+    /** {@link stationChannels} over the current roster, recomputed only when the roster itself is replaced. */
+    private stationChannelMap;
     /**
      * Resolve the capability set of the device a P2P frame belongs to — the `(station, channel)` pair
      * (a station fans out to attached devices by `device_channel`; a standalone device is its own

package/dist/core/contracts.d.ts

@@ -129,6 +129,27 @@ export declare class StationUnreachableError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * Work on a device was refused: its channel within its station cannot be established from the device records.
+ *
+ * A device attached to a HomeBase is addressed by a channel within that station: a media start and every
+ * per-channel command name it. When its record states no channel, or another device attached to the same station
+ * states the same one, any channel chosen would address whichever device actually holds it (streaming another
+ * camera's video under this serial), so nothing is sent. The `station-channel-unresolved` trace says which.
+ */
+export declare class DeviceChannelUnresolvedError extends Error {
+    /** The device that could not be addressed. */
+    readonly sn: string;
+    /** The station it is attached to. */
+    readonly stationSn: string;
+    constructor(
+    /** The device that could not be addressed. */
+    sn: string, 
+    /** The station it is attached to. */
+    stationSn: string, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * How a live stream ended before its first video keyframe: the warm-up deadline elapsed, the source
  * reported an error, or the source ended on its own.

package/dist/core/solix-types.d.ts

@@ -98,6 +98,12 @@ export interface SolixSceneSolarbank {
     bat_temperature?: string | number;
     /** State of charge, % (string on the wire). Cross-checks the `ff09` `0xa3` SOC. */
     bat_soc?: string | number;
+    /**
+     * Number of ATTACHED expansion battery packs — the built-in battery is the host, not a pack. Read as
+     * `expansionPacks`. Observed live as `0` on a standalone AE103 main unit; a populated value (and the
+     * matching per-pack `bms_list` detail) has not yet been captured with a pack attached.
+     */
+    sub_package_num?: string | number;
     [k: string]: unknown;
 }
 /**

package/dist/index.js

@@ -2898,6 +2898,16 @@ var StationUnreachableError = class extends Error {
     this.name = "StationUnreachableError";
   }
 };
+var DeviceChannelUnresolvedError = class extends Error {
+  sn;
+  stationSn;
+  constructor(sn, stationSn, options) {
+    super(`${sn} has no usable channel on station ${stationSn}, so nothing was sent to it`, options);
+    this.sn = sn;
+    this.stationSn = stationSn;
+    this.name = "DeviceChannelUnresolvedError";
+  }
+};
 var LiveStreamStartError = class extends Error {
   reason;
   stage;
@@ -14138,6 +14148,9 @@ function solarbankSceneReadings(scene) {
     const soc = sceneNum(sb.bat_soc);
     if (soc !== void 0)
       values.batterySoc = soc;
+    const packs = sceneNum(sb.sub_package_num);
+    if (packs !== void 0)
+      values.expansionPacks = packs;
     if (Object.keys(values).length > 0)
       out.push({ deviceSn, values });
   }
@@ -20016,6 +20029,50 @@ var FragmentRecording = class extends EventEmitter6 {
   }
 };
 
+// dist/transport/p2p/station-channels.js
+function resolvedStationSn(raw, sn) {
+  const parent = typeof raw.parent_sn === "string" && raw.parent_sn ? raw.parent_sn : void 0;
+  if (parent && parent !== sn)
+    return parent;
+  const station = typeof raw.station_sn === "string" && raw.station_sn ? raw.station_sn : void 0;
+  return station ?? sn;
+}
+function stationOf(dev) {
+  const raw = dev.raw ?? {};
+  const parent = typeof raw.parent_sn === "string" && raw.parent_sn && raw.parent_sn !== dev.sn ? raw.parent_sn : void 0;
+  return parent ?? dev.stationSn ?? resolvedStationSn(raw, dev.sn);
+}
+function statedChannel(dev) {
+  const v = dev.raw?.device_channel;
+  return typeof v === "number" ? v : void 0;
+}
+function stationChannels(devices) {
+  const out = /* @__PURE__ */ new Map();
+  const claimants = /* @__PURE__ */ new Map();
+  for (const d of devices) {
+    const station = stationOf(d);
+    const stated = statedChannel(d);
+    if (d.sn === station || stated === void 0)
+      continue;
+    const counts = claimants.get(station) ?? /* @__PURE__ */ new Map();
+    counts.set(stated, (counts.get(stated) ?? 0) + 1);
+    claimants.set(station, counts);
+  }
+  for (const d of devices) {
+    const station = stationOf(d);
+    const stated = statedChannel(d);
+    if (d.sn === station)
+      out.set(d.sn, { channel: stated ?? 0 });
+    else if (stated === void 0)
+      out.set(d.sn, { issue: "missing" });
+    else if ((claimants.get(station)?.get(stated) ?? 0) > 1)
+      out.set(d.sn, { issue: "shared", claimed: stated });
+    else
+      out.set(d.sn, { channel: stated });
+  }
+  return out;
+}
+
 // dist/transport/p2p/command-router.js
 var DIRECT_CMD_SENDS = 5;
 function abortable(work, signal) {
@@ -20169,11 +20226,6 @@ var P2PCommandRouter = class _P2PCommandRouter {
   recordFor(sn) {
     return this.deps.listDevices().find((d) => d.sn === sn);
   }
-  /** The parent-station key a device's session lives under (its HomeBase, or itself if standalone). */
-  stationKeyFor(dev) {
-    const raw = dev.raw ?? {};
-    return raw.parent_sn && raw.parent_sn !== dev.sn ? raw.parent_sn : dev.stationSn ?? dev.sn;
-  }
   /**
    * The parent-station serial a device serial's session lives under — the single source of truth for
    * session keying, used by the facade (e.g. to pre-warm the right station for an event). Returns the
@@ -20181,14 +20233,14 @@ var P2PCommandRouter = class _P2PCommandRouter {
    */
   stationKeyOf(sn) {
     const dev = this.recordFor(sn);
-    return dev ? this.stationKeyFor(dev) : sn;
+    return dev ? stationOf(dev) : sn;
   }
   /** Reset only a standalone device's session; an attached device must not close its shared HomeBase. */
   async resetStandaloneSession(sn) {
     const device = this.recordFor(sn);
     if (!device)
       return;
-    const station = this.stationKeyFor(device);
+    const station = stationOf(device);
     if (station === sn)
       await this.manager.resetWhenUnused(station);
   }
@@ -20400,7 +20452,7 @@ var P2PCommandRouter = class _P2PCommandRouter {
     const dev = this.recordFor(sn);
     if (!dev)
       throw new Error(`device ${sn} not found`);
-    await this.openSession(this.stationKeyFor(dev), this.stationKeyFor(dev));
+    await this.openSession(stationOf(dev), stationOf(dev));
     return dev;
   }
   /**
@@ -21188,8 +21240,8 @@ var P2PCommandRouter = class _P2PCommandRouter {
   async resolveSession(sn, opts = {}, rebuilt = false) {
     const dev = await this.deviceFor(sn);
     const raw = dev.raw ?? {};
-    const homeBaseAttached = !!raw.parent_sn && raw.parent_sn !== sn;
-    const parentSn = homeBaseAttached ? raw.parent_sn : dev.stationSn ?? sn;
+    const parentSn = stationOf(dev);
+    const homeBaseAttached = parentSn !== sn;
     const session = this.manager.get(parentSn) ?? this.manager.get(sn) ?? (dev.stationSn ? this.manager.get(dev.stationSn) : void 0);
     if (!session) {
       const stations = this.manager.keys().filter((k) => !_P2PCommandRouter.isMediaSessionKey(k));
@@ -21200,8 +21252,13 @@ var P2PCommandRouter = class _P2PCommandRouter {
       await this.manager.close(parentSn).catch((error) => this.reportError(error instanceof Error ? error : new Error(String(error))));
       return await this.resolveSession(sn, opts, true);
     }
+    const address = stationChannels(this.deps.listDevices()).get(sn);
+    if (!("channel" in address)) {
+      this.traceOnStation(session, { phase: "station-channel-unresolved", issue: address.issue });
+      throw new DeviceChannelUnresolvedError(sn, parentSn);
+    }
     this.manager.bumpCommand(parentSn, parentSn);
-    const channel = typeof raw.device_channel === "number" ? raw.device_channel : 0;
+    const { channel } = address;
     const stationAdminId = raw.member?.admin_user_id;
     const stationModel = this.recordFor(parentSn)?.model;
     const accountId = stationAdminId ?? this.deps.mega.auth?.userId ?? "";
@@ -24149,13 +24206,6 @@ function mediaFailureTag(error) {
 }
 
 // dist/client/device-registry.js
-function resolvedStationSn(raw, sn) {
-  const parent = typeof raw.parent_sn === "string" && raw.parent_sn ? raw.parent_sn : void 0;
-  if (parent && parent !== sn)
-    return parent;
-  const station = typeof raw.station_sn === "string" && raw.station_sn ? raw.station_sn : void 0;
-  return station ?? sn;
-}
 function mergeParams(raw, params, paramUpdatedAt) {
   for (const p of raw ?? []) {
     if (!p || p.param_type == null || p.param_value == null)
@@ -24197,6 +24247,9 @@ var DeviceRegistry = class {
   devices = [];
   /** Per-(station, channel) capability cache for {@link capabilitiesForFrame}; `null` = negative hit. */
   frameCapsCache = /* @__PURE__ */ new Map();
+  /** {@link stationChannels} of {@link channelMapFor}, the roster it was computed over. */
+  channelMap = /* @__PURE__ */ new Map();
+  channelMapFor;
   /**
    * Serials whose per-device param overlay has been refused. The call is owner-gated, so on a shared or
    * member account it fails for the whole life of the client — retrying it every refresh spends a request
@@ -24464,7 +24517,7 @@ var DeviceRegistry = class {
     }
     const raw = dev.raw;
     const deviceType = typeof raw?.["device_type"] === "number" ? raw["device_type"] : void 0;
-    const station = this.stationOf(dev);
+    const station = stationOf(dev);
     return {
       deviceType,
       model: dev.model,
@@ -24612,43 +24665,47 @@ var DeviceRegistry = class {
   serialForFrame(stationSn, channel) {
     return this.deviceForFrame(stationSn, channel)?.sn;
   }
-  /**
-   * The parent station a device's frames arrive under.
-   *
-   * `parent_sn` on the cloud record is the field that is actually populated for a HomeBase-attached
-   * device — `stationSn` is frequently absent (observed empty on every attached sensor of a T8010),
-   * so keying on it alone silently resolves an attached device to ITSELF and no frame ever matches.
-   * Mirrors the router's own session-keying precedence, which is the source of truth for which
-   * station a device's traffic belongs to. Answering the device's OWN serial is what "stands alone"
-   * means, so this is also the topology signal `record()`/`capsOf` hand the resolver.
-   */
-  stationOf(dev) {
-    return dev.stationSn ?? resolvedStationSn(dev.raw ?? {}, dev.sn);
-  }
   /**
    * The device a `(station, channel)` pair refers to — a station fans out to attached devices by
    * `device_channel`, while a standalone device is its own station at channel 0.
    *
-   * A device claims a channel only when its record actually STATES one. Treating a missing
-   * `device_channel` as 0 turns every such device into a rival claimant for channel 0, where a
-   * station legitimately has an attached device already, and the winner is then decided by cloud list
-   * order — so the same frame resolves to different devices across refreshes. The resolved serial now
-   * decides where realtime state is written, not just which decoders may run, so an ambiguous answer
+   * A device claims a channel only when its record actually STATES one that no other device attached to
+   * the same station also states ({@link stationChannels}). Treating a missing `device_channel` as 0, or
+   * letting two claimants of one channel both hold it, leaves the winner to cloud list order — which a
+   * partial refresh reorders — so the same frame resolves to different devices across refreshes. The resolved
+   * serial decides where realtime state is written, not just which decoders may run, so an ambiguous answer
    * writes one device's params onto another.
    *
    * An attached device that names the channel wins over the station itself, which is what a station
-   * fanning traffic out by channel means; the station answers for channel 0 only when nothing is
-   * attached there, which is also the standalone case (a device is its own station).
+   * fanning traffic out by channel means. A channel two attached devices both state belongs to one of them,
+   * which cannot be told apart, so it answers nothing rather than the station. The station answers for
+   * channel 0 only when nothing attached states it, which is also the standalone case (a device is its own
+   * station).
    */
   deviceForFrame(stationSn, channel) {
-    const attached = this.devices.find((d) => {
-      const stated = d.raw?.device_channel;
-      return typeof stated === "number" && stated === channel && d.sn !== stationSn && this.stationOf(d) === stationSn;
-    });
-    if (attached)
-      return attached;
+    const channels = this.stationChannelMap();
+    let claimed = false;
+    for (const d of this.devices) {
+      if (d.sn === stationSn || stationOf(d) !== stationSn)
+        continue;
+      const c = channels.get(d.sn);
+      if (c && "channel" in c && c.channel === channel)
+        return d;
+      if (c && "claimed" in c && c.claimed === channel)
+        claimed = true;
+    }
+    if (claimed)
+      return void 0;
     return channel === 0 ? this.devices.find((d) => d.sn === stationSn) : void 0;
   }
+  /** {@link stationChannels} over the current roster, recomputed only when the roster itself is replaced. */
+  stationChannelMap() {
+    if (this.channelMapFor !== this.devices) {
+      this.channelMap = stationChannels(this.devices);
+      this.channelMapFor = this.devices;
+    }
+    return this.channelMap;
+  }
   /**
    * Resolve the capability set of the device a P2P frame belongs to — the `(station, channel)` pair
    * (a station fans out to attached devices by `device_channel`; a standalone device is its own
@@ -24697,7 +24754,7 @@ var DeviceRegistry = class {
   /** Resolve a record's capabilities the way `getDevice` does, so gating matches `device.has()`. */
   capsOf(dev) {
     const raw = dev.raw ?? {};
-    const station = this.stationOf(dev);
+    const station = stationOf(dev);
     return new Set(resolveDevice({
       deviceType: raw.device_type,
       model: dev.model,
@@ -27144,8 +27201,9 @@ var SolixClient = class _SolixClient {
    * 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).
+   * app-synced source for `chargeUpperLimit`. `backupReserve` (with its enable switch) also has a second
+   * source under the same name, the realtime MQTT `b5` frame; whether the two agree while the switch is
+   * OFF is not yet verified. Verified live against a known AE103 setting (discharge 20 / charge 80).
    */
   async getSafetySocParams(siteId) {
     const p = await this.getSiteDeviceParam(siteId, _SolixClient.SOC_PARAM_TYPE);
@@ -27359,6 +27417,13 @@ function addSolarbankScalars(frame, out) {
   if (b5 && b5[0] === 4 && b5.length === 4) {
     out.dischargeLimit = b5[1];
     out.chargeLimit = b5[3];
+  } else if (b5 && b5[0] === 4 && b5.length === 25) {
+    out.backupReserve = b5[1];
+  }
+  const df = frame.fields.get(223);
+  if (df && df[0] === 4 && df.length >= 7) {
+    out.gridImportLimit = df.readUInt16LE(3);
+    out.gridExportLimit = df.readUInt16LE(5);
   }
 }
 var SolixMqtt = class extends EventEmitter10 {
@@ -27758,6 +27823,7 @@ export {
   DOCK_KINDS,
   DOORBELL_MEMBERS,
   Device,
+  DeviceChannelUnresolvedError,
   DoorbellPushEvent,
   DoorbellRingtone,
   EMPTY_CLEAN_RECORD_PAGE,