@mega-yfue/eufy-sdk 0.6.0-beta.18 → 0.6.0-beta.19

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

@@ -248,6 +248,12 @@ export declare class DeviceRegistry {
      * for an expired token is the same lie {@link getDevices} stopped telling, one level down.
      */
     refreshedList(sn: string): Promise<EufyDevice | undefined>;
+    /**
+     * Record that `sn` was heard on a realtime wire at `atMs`, advancing its {@link EufyDevice.lastSeenMs}.
+     *
+     * Only ever moves the time forward, and survives a {@link getDevices} rebuild.
+     */
+    markSeen(sn: string, atMs: number): void;
     /**
      * Record state a device reported over its realtime wire, merging into whatever it last reported.
      *

package/dist/client/eufy-mega.d.ts

@@ -129,6 +129,12 @@ export declare class EufyMega extends EventEmitter {
     private readonly pollTimer;
     /** Armed while a failed push bring-up waits to be retried; cancelled by {@link disconnect}. */
     private readonly pushRetryTimer;
+    /**
+     * Per wired station, the pending reopen of its session and the pause before the next one; see
+     * {@link reopenWiredStation}. Dropped for a station when its session connects, and wholly by
+     * {@link disconnect}.
+     */
+    private readonly stationReopens;
     constructor(opts: EufyMegaOptions);
     /**
      * Builds the inbound listener that converts ThingClips DP maps to realtime capability state.
@@ -313,7 +319,16 @@ export declare class EufyMega extends EventEmitter {
      * manager's own log, since by then nothing is waiting to receive it.
      */
     private recycleStandaloneSession;
-    /** Reopen a wired station that {@link recycleStandaloneSession} closed, while the generation that warmed it is current. */
+    /**
+     * Reopen a wired station's session while the generation that warmed it is current: after
+     * {@link recycleStandaloneSession} closed it, after it closed on its own, or after its warm-up failed.
+     *
+     * A wired station's session is the persistent one realtime start opened, so a station left without one
+     * receives nothing until a command dials it again. The first reopen runs at once; one that fails is
+     * retried after {@link STATION_REOPEN_MIN_MS}, doubling up to {@link STATION_REOPEN_MAX_MS}, until the
+     * session connects or the generation ends. One reopen is pending per station at a time, and each failure
+     * is reported once, by {@link P2PCommandRouter.ensureStation}.
+     */
     private reopenWiredStation;
     /**
      * Whether the DECODED property now reads what the write asked for.
@@ -339,6 +354,8 @@ export declare class EufyMega extends EventEmitter {
      * fans same-kind sensors out by channel, so the resolved serial is folded in; a payload's own
      * fields still win on conflict.
      *
+     * A station's camera-info table lands per channel, each channel's params on the device attached there.
+     *
      * Params the station volunteered land as device state first. They arrive in the cloud record's own
      * `param_type → value` shape, so no capability has to claim an id it does not own, and the reads
      * they back stop waiting for the next cloud poll. A capability decode follows for the frames that
@@ -754,7 +771,8 @@ export declare class EufyMega extends EventEmitter {
      */
     keepStationWarm(stationSn: string): () => void;
     /** Eagerly open P2P sessions for WIRED stations only (persistent — they don't drain). Battery
-     *  stations stay closed until an on-demand open. Best-effort per station. */
+     *  stations stay closed until an on-demand open. Best-effort per station: one that fails is handed to
+     *  {@link reopenWiredStation}. */
     private warmWiredP2P;
     /**
      * A station's power tier for the P2P lifecycle: a HomeBase/station is `"wired"` (persistent); a

package/dist/client/types.d.ts

@@ -202,9 +202,11 @@ export interface EufyMegaOptions extends MegaClientConfig {
  * that choice on every host. The SDK reports when the device last spoke; the caller decides what that
  * means — the same split as the snapshot cache TTL and the live power budget.
  *
- * P2P session state is **not** a liveness signal and is not carried here: sessions are opened only
- * when something needs one and closed when idle, so "no session" is the resting state of a healthy
- * device. Transport visibility lives on `getP2pSessions()` and the `p2pConnect`/`p2pClose` events,
+ * The absence of a P2P session is **not** a liveness signal and is not carried here: sessions are opened
+ * only when something needs one and closed when idle, so "no session" is the resting state of a healthy
+ * device. A station answering an open session is the opposite fact, positive evidence, and does advance
+ * the station's own {@link DeviceState.lastSeenMs} — never that of a device it covers, whose liveness its answer does
+ * not show. Transport visibility lives on `getP2pSessions()` and the `p2pConnect`/`p2pClose` events,
  * station-scoped like the session itself.
  *
  * The cloud record carries no connectivity field either: it has no `status` / `device_online`, and the
@@ -215,8 +217,9 @@ export interface DeviceState {
     /** The parent station whose P2P session covers this device (itself, when standalone). */
     stationSn: string;
     /**
-     * When the device last reported to the cloud, in ms. Bounded by
-     * the cloud's own slow refresh — minutes, not seconds — so it answers "is this device alive at all",
+     * When the device was last heard from, in ms: its last report to the cloud, or a later one over a
+     * realtime wire, a station's heartbeat answer on its open P2P session included. The cloud half is bounded
+     * by the cloud's own slow refresh — minutes, not seconds — so it answers "is this device alive at all",
      * not "what is it doing right now".
      */
     lastSeenMs?: number;
@@ -332,7 +335,7 @@ export type EufyMegaEventMap = {
         map: VacuumMapSnapshot;
     }];
     /**
-     * A device reported to the cloud since the last poll — its {@link DeviceState.lastSeenMs} advanced.
+     * A device was heard from since the last poll — its {@link DeviceState.lastSeenMs} advanced.
      * Carries {@link DeviceState}; the host applies its own staleness threshold.
      *
      * Transport/session lifecycle is NOT this event: that's `p2pConnect`/`p2pClose`, station-scoped where

package/dist/core/types.d.ts

@@ -80,8 +80,10 @@ export interface EufyDevice {
      */
     paramUpdatedAt?: Record<number, number>;
     /**
-     * The most recent {@link paramUpdatedAt} across all of this device's params, in **milliseconds**
-     * (comparable to `Date.now()` directly). `undefined` when the record carried no timestamp at all.
+     * When the device was last heard from, in **milliseconds** (comparable to `Date.now()` directly): the
+     * most recent {@link paramUpdatedAt} across all of its params, or a later report over a realtime wire,
+     * including a station answering its own P2P session's heartbeat. Never moves backwards. `undefined` when
+     * neither has been seen.
      *
      * This is an observation — "the device last reported at T" — deliberately **not** a reachability
      * verdict. How long a silence means "unreachable" depends on the device (a mains camera heartbeats

package/dist/index.js

@@ -2981,16 +2981,13 @@ var BIZ_PROTOCOL = {
 var BIZ_CHANNEL = {
   /** Scene (room-group) data. Hard-coded in the app, not part of `ChanIds`. */
   SCENES: 0,
-  MAP_INFO: 1,
-  PATH: 2,
-  ROOM_OUTLINE: 3,
-  ROOM_PARAMS: 4,
-  RESTRICTED_ZONE: 5,
-  DYNAMIC_DATA: 6,
-  TEMPORARY_DATA: 7,
-  OBSTACLE_INFO: 8,
-  MAP_DATA: 9,
-  CRUISE_DATA: 10
+  MAP_DATA: 2,
+  ROOM_OUTLINE: 4,
+  ROOM_PARAMS: 5,
+  RESTRICTED_ZONE: 6,
+  DYNAMIC_DATA: 7,
+  MAP_DESCRIPTION: 60,
+  MAP_BACKUP: 68
 };
 var BY_ID = new Map(Object.entries(BIZ_CHANNEL).map(([name, id]) => [id, name]));
 function bizChannelName(id) {
@@ -6828,17 +6825,15 @@ var LIGHT_MEMBERS = {
     writeAs: "setEnabled"
   }
 };
+var NO_SPOTLIGHT_MODELS = /* @__PURE__ */ new Set(["T8171", "T8416"]);
 var LIGHT = {
   capability: "light",
   description: "Floodlight / spotlight manual switch and brightness.",
   members: LIGHT_MEMBERS,
   properties: propertiesOf(LIGHT_MEMBERS),
-  // Three T8171 units on firmware 1.2.1.6 report 1400/1401/1403 without a spotlight, so those
-  // param ids are not sufficient evidence for that model. The camera status LED (1045) is not light.
-  // Other models keep the existing param and name evidence.
   detection: {
     modelHints: [/floodlight|wall.?light|spot.?light|search.?light/i],
-    detect: (record) => record.model !== "T8171" && [1400, 1401, 1403, 6080, 6082, 1413].some((param) => Object.hasOwn(record.params ?? {}, param))
+    detect: (record) => !NO_SPOTLIGHT_MODELS.has(record.model ?? "") && [1400, 1401, 1403, 6080, 6082, 1413].some((param) => Object.hasOwn(record.params ?? {}, param))
   },
   /**
    * Only what the member table cannot express: `on`/`off` as no-argument verbs over the same wire as the
@@ -15211,7 +15206,9 @@ var READER_BY_CHANNEL = {
   ROOM_OUTLINE: reader("outline", decodeVacuumRoomOutline),
   ROOM_PARAMS: reader("rooms", decodeVacuumRoomParams),
   RESTRICTED_ZONE: reader("zones", decodeVacuumRestrictedZones),
-  DYNAMIC_DATA: reader("pose", decodeVacuumPose)
+  DYNAMIC_DATA: reader("pose", decodeVacuumPose),
+  MAP_DESCRIPTION: reader("description", decodeVacuumMapDescription),
+  MAP_BACKUP: reader("backup", decodeVacuumMapBackup)
 };
 var DECODED_MAP_CHANNELS = Object.keys(READER_BY_CHANNEL);
 var READERS = new Map(DECODED_MAP_CHANNELS.map((name) => [BIZ_CHANNEL[name], READER_BY_CHANNEL[name]]));
@@ -16353,6 +16350,19 @@ function paramReport(payload) {
   }
   return Object.keys(out).length ? out : void 0;
 }
+function channelReport(payload) {
+  const list = payload?.params;
+  if (!Array.isArray(list))
+    return void 0;
+  const out = {};
+  for (const entry of list) {
+    const p = entry;
+    if (typeof p?.dev_type !== "number" || typeof p.param_type !== "number" || p.param_value == null)
+      continue;
+    (out[p.dev_type] ??= {})[p.param_type] = String(p.param_value);
+  }
+  return Object.keys(out).length ? out : void 0;
+}
 var traceSequence = 0;
 function firstTableRows(text2) {
   const decoded = Buffer.from(text2, "latin1").toString("utf8");
@@ -16434,7 +16444,12 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
   audioStalled = false;
   audioRetransmitTimer;
   lastPongData;
-  /** When the selected peer last answered outbound P2P traffic on this connection. */
+  /**
+   * When the selected peer last answered outbound P2P traffic on this connection.
+   *
+   * Each answer also emits `peerAnswer` with this time: a PONG or an ACK from the connected address is the
+   * station replying on this connection now, which a heartbeat draws every {@link HEARTBEAT_MS}.
+   */
   lastPeerAt;
   /** Whether the silence has already been stated, so it is traced once per connection rather than per read. */
   pathStaleTraced = false;
@@ -17073,6 +17088,7 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
     if (fromConnectedPeer && (hasHeader(msg, ResponseMessageType.PONG) || hasHeader(msg, ResponseMessageType.ACK))) {
       this.lastPeerAt = Date.now();
       this.pathStaleTraced = false;
+      this.emit("peerAnswer", this.lastPeerAt);
     }
     if (!hasHeader(msg, ResponseMessageType.DATA)) {
       this.logger.debug(`[p2p] ${this.cfg.stationSn} <<< ${rinfo.address}:${rinfo.port} header=${msg.subarray(0, 2).toString("hex")} len=${msg.length}`);
@@ -18404,7 +18420,11 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
         frame.json = JSON.parse(text2);
       } catch {
       }
-      const reported = header.commandId === CMD_NOTIFY_PAYLOAD ? paramReport(frame.json?.payload) : header.commandId === CMD_CAMERA_INFO ? paramReport(frame.json) : void 0;
+      const stationTable = header.commandId === CMD_CAMERA_INFO && header.channel === STATION_CHANNEL3;
+      const byChannel = stationTable ? channelReport(frame.json) : void 0;
+      const reported = header.commandId === CMD_NOTIFY_PAYLOAD ? paramReport(frame.json?.payload) : header.commandId === CMD_CAMERA_INFO && !stationTable ? paramReport(frame.json) : void 0;
+      if (byChannel)
+        frame.channelParams = byChannel;
       if (reported)
         frame.params = reported;
     }
@@ -22657,6 +22677,10 @@ var P2PCommandRouter = class _P2PCommandRouter {
       this.tearDownStation(stationSn);
     });
     session.on("level2Ready", ({ cipherId }) => this.deps.onLevel2Ready(stationSn, cipherId));
+    session.on("peerAnswer", (atMs) => {
+      if (this.manager.get(stationSn) === session)
+        this.deps.onPeerAnswer?.(stationSn, atMs);
+    });
     session.on("data", (f) => this.deps.onFrame(stationSn, f));
     return session;
   }
@@ -28872,12 +28896,15 @@ function mergeParams(raw, params, paramUpdatedAt) {
       paramUpdatedAt[p.param_type] = ts;
   }
 }
+function newest(a, b) {
+  return a === void 0 ? b : b === void 0 ? a : Math.max(a, b);
+}
 function lastSeenMsOf(paramUpdatedAt) {
-  let newest = 0;
+  let newest2 = 0;
   for (const ts of Object.values(paramUpdatedAt))
-    if (ts > newest)
-      newest = ts;
-  return newest > 0 ? newest * 1e3 : void 0;
+    if (ts > newest2)
+      newest2 = ts;
+  return newest2 > 0 ? newest2 * 1e3 : void 0;
 }
 var CLASS_BY_CODEC = {
   station: "homebase",
@@ -28999,6 +29026,7 @@ var DeviceRegistry = class {
       this.onError(e);
     }
     const seen = /* @__PURE__ */ new Map();
+    const prior = new Map(this.devices.map((d) => [d.sn, d.lastSeenMs]));
     for (const body of bodies) {
       let res;
       try {
@@ -29033,7 +29061,7 @@ var DeviceRegistry = class {
           p2pDid: raw.p2p_did,
           params,
           paramUpdatedAt,
-          lastSeenMs: lastSeenMsOf(paramUpdatedAt),
+          lastSeenMs: newest(lastSeenMsOf(paramUpdatedAt), prior.get(raw.device_sn)),
           raw,
           deviceClass,
           ...c
@@ -29269,6 +29297,16 @@ var DeviceRegistry = class {
       return void 0;
     }
   }
+  /**
+   * Record that `sn` was heard on a realtime wire at `atMs`, advancing its {@link EufyDevice.lastSeenMs}.
+   *
+   * Only ever moves the time forward, and survives a {@link getDevices} rebuild.
+   */
+  markSeen(sn, atMs) {
+    const dev = this.devices.find((d) => d.sn === sn);
+    if (dev)
+      dev.lastSeenMs = newest(dev.lastSeenMs, atMs);
+  }
   /**
    * Record state a device reported over its realtime wire, merging into whatever it last reported.
    *
@@ -29283,9 +29321,7 @@ var DeviceRegistry = class {
     if (!Object.keys(params).length)
       return;
     this.dpParams.set(sn, { ...this.dpParams.get(sn), ...params });
-    const dev = this.devices.find((d) => d.sn === sn);
-    if (dev)
-      dev.lastSeenMs = Date.now();
+    this.markSeen(sn, Date.now());
     this.deviceCapsCache.delete(sn);
     const waiters = this.stateWaiters.get(sn);
     if (waiters) {
@@ -29494,6 +29530,8 @@ var DEFAULT_PREWARM_TIERS = ["wired", "battery"];
 var SESSION_RECYCLE_WAIT_MS = 5e3;
 var PUSH_RETRY_MIN_MS = 3e4;
 var PUSH_RETRY_MAX_MS = 6e5;
+var STATION_REOPEN_MIN_MS = 5e3;
+var STATION_REOPEN_MAX_MS = 3e5;
 var RealtimeStartupSupersededError = class extends Error {
 };
 var RefreshWindowClosedError = class extends Error {
@@ -29600,6 +29638,12 @@ var EufyMega = class extends EventEmitter14 {
   pollTimer = new Timer();
   /** Armed while a failed push bring-up waits to be retried; cancelled by {@link disconnect}. */
   pushRetryTimer = new Timer();
+  /**
+   * Per wired station, the pending reopen of its session and the pause before the next one; see
+   * {@link reopenWiredStation}. Dropped for a station when its session connects, and wholly by
+   * {@link disconnect}.
+   */
+  stationReopens = /* @__PURE__ */ new Map();
   constructor(opts) {
     super();
     this.opts = opts;
@@ -29633,10 +29677,18 @@ var EufyMega = class extends EventEmitter14 {
       ensureDevices: async () => {
         await this.registry.getDevices();
       },
-      onConnect: (sn) => this.emit("p2pConnect", sn),
-      onClose: (sn) => this.emit("p2pClose", sn),
+      onConnect: (sn) => {
+        this.stationReopens.get(sn)?.timer.cancel();
+        this.stationReopens.delete(sn);
+        this.emit("p2pConnect", sn);
+      },
+      onClose: (sn) => {
+        this.emit("p2pClose", sn);
+        this.reopenWiredStation(sn);
+      },
       onError: (e) => this.reportError(e),
       onLevel2Ready: (sn, cipherId) => this.emit("p2pLevel2Ready", { stationSn: sn, cipherId }),
+      onPeerAnswer: (sn, atMs) => this.registry.markSeen(sn, atMs),
       onFrame: (stationSn, f) => this.onP2PFrame(stationSn, f)
     });
     this.rtc = new RtcCommandRouter({
@@ -30109,7 +30161,16 @@ var EufyMega = class extends EventEmitter14 {
       releaseWrite.then(() => this.opts.logger?.debug(`[session ${sn}] recycle still waiting on an attached viewer \u2014 releasing the write that asked for it`))
     ]);
   }
-  /** Reopen a wired station that {@link recycleStandaloneSession} closed, while the generation that warmed it is current. */
+  /**
+   * Reopen a wired station's session while the generation that warmed it is current: after
+   * {@link recycleStandaloneSession} closed it, after it closed on its own, or after its warm-up failed.
+   *
+   * A wired station's session is the persistent one realtime start opened, so a station left without one
+   * receives nothing until a command dials it again. The first reopen runs at once; one that fails is
+   * retried after {@link STATION_REOPEN_MIN_MS}, doubling up to {@link STATION_REOPEN_MAX_MS}, until the
+   * session connects or the generation ends. One reopen is pending per station at a time, and each failure
+   * is reported once, by {@link P2PCommandRouter.ensureStation}.
+   */
   reopenWiredStation(sn) {
     const generation = this.realtimeGeneration;
     if (generation?.epoch !== this.realtimeEpoch)
@@ -30118,9 +30179,18 @@ var EufyMega = class extends EventEmitter14 {
       return;
     if (this.stationPower(sn) !== "wired")
       return;
-    void this.p2p.ensureStation(sn, generation.abort.signal).catch((error) => {
-      if (!generation.abort.signal.aborted)
-        this.reportError(error);
+    const reopen = this.stationReopens.get(sn) ?? { timer: new Timer(), delayMs: 0 };
+    this.stationReopens.set(sn, reopen);
+    if (reopen.timer.pending)
+      return;
+    reopen.timer.arm(reopen.delayMs, () => {
+      if (generation.epoch !== this.realtimeEpoch)
+        return;
+      reopen.delayMs = Math.min(Math.max(reopen.delayMs * 2, STATION_REOPEN_MIN_MS), STATION_REOPEN_MAX_MS);
+      void this.p2p.ensureStation(sn, generation.abort.signal).catch(() => {
+        if (!generation.abort.signal.aborted && this.stationReopens.get(sn) === reopen)
+          this.reopenWiredStation(sn);
+      });
     });
   }
   /**
@@ -30163,6 +30233,8 @@ var EufyMega = class extends EventEmitter14 {
    * fans same-kind sensors out by channel, so the resolved serial is folded in; a payload's own
    * fields still win on conflict.
    *
+   * A station's camera-info table lands per channel, each channel's params on the device attached there.
+   *
    * Params the station volunteered land as device state first. They arrive in the cloud record's own
    * `param_type → value` shape, so no capability has to claim an id it does not own, and the reads
    * they back stop waiting for the next cloud poll. A capability decode follows for the frames that
@@ -30181,6 +30253,8 @@ var EufyMega = class extends EventEmitter14 {
     };
     if (f.params)
       this.applyRealtimeState(deviceSn, f.params);
+    for (const [channel, params] of Object.entries(f.channelParams ?? {}))
+      this.applyRealtimeState(this.registry.serialForFrame(stationSn, Number(channel)), params);
     this.applyRealtimeReport(deviceSn, decodeState(signal, caps));
     for (const ev of decodeEvent(signal, caps))
       this.emitSemantic(ev.event, deviceSn ? { deviceSn, ...ev.payload } : ev.payload, {
@@ -31063,7 +31137,8 @@ var EufyMega = class extends EventEmitter14 {
     return this.rtc.keepWarm(route);
   }
   /** Eagerly open P2P sessions for WIRED stations only (persistent — they don't drain). Battery
-   *  stations stay closed until an on-demand open. Best-effort per station. */
+   *  stations stay closed until an on-demand open. Best-effort per station: one that fails is handed to
+   *  {@link reopenWiredStation}. */
   async warmWiredP2P(readiness = createPlaneReadiness(), signal) {
     const wired = /* @__PURE__ */ new Set();
     for (const d of this.registry.p2pDevices()) {
@@ -31081,6 +31156,7 @@ var EufyMega = class extends EventEmitter14 {
         return;
       readiness.failed++;
       readiness.pending--;
+      this.reopenWiredStation(sn);
     })));
     return readiness;
   }
@@ -31755,6 +31831,9 @@ var EufyMega = class extends EventEmitter14 {
   async teardownRealtime() {
     this.pollTimer.cancel();
     this.pushRetryTimer.cancel();
+    for (const { timer } of this.stationReopens.values())
+      timer.cancel();
+    this.stationReopens.clear();
     this.lastStateAnnounced.clear();
     await this.closeMqttTransports();
     this.rtc.close();