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

package/dist/core/contracts.d.ts

@@ -74,6 +74,61 @@ export declare class CameraDisabledError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * Work on a station was refused: the station did not provide the session key that work requires.
+ *
+ * A station reached over its HomeBase encrypts what it is sent under a key negotiated once per connection, and
+ * a media start for an attached camera has no unencrypted form at all — so without that key there is nothing
+ * to send, however reachable the station is. Naming this apart from a source that failed is what separates an
+ * account whose cipher material could not be resolved from a camera that is off, a station that is busy, or a
+ * stream that produced nothing: they share no next step.
+ *
+ * The `level2-unavailable` trace states WHY the key is not coming. This states only that it is not, because
+ * that is what the refusal itself knows.
+ *
+ * `stationSn` is the station that owed the key, which is the parent for an attached camera and therefore not
+ * the serial the refused call was made about: several cameras refused at once are one station's outcome, and
+ * nothing else in the refusal says so.
+ */
+export declare class StationKeyUnavailableError extends Error {
+    /** The station whose session key did not arrive. */
+    readonly stationSn: string;
+    /** Always true: the negotiation is per connection, so a later one may still produce a key. */
+    readonly retryable = true;
+    constructor(
+    /** The station whose session key did not arrive. */
+    stationSn: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Work on a station was refused: its session did not connect within the wait it was given.
+ *
+ * A station is reached over its own session, and nothing addressed to it — a media start, a property read, a
+ * still — can be attempted before that session is up. Naming this apart from every other failure is what tells
+ * a station that could not be reached at all from one that answered and then refused, or one that served media
+ * a caller could not use: those call for opposite next steps, and a caller cannot infer which it had from a
+ * message.
+ *
+ * `waitedMs` is how long was actually waited, which a caller compares against its own deadline to know whether
+ * this SDK concluded or its own bound expired first. `stationSn` is the station that could not be reached —
+ * the parent for an attached camera, so it is not derivable from the serial the call was made about.
+ */
+export declare class StationUnreachableError extends Error {
+    /** The station whose session did not connect. */
+    readonly stationSn: string;
+    /** How long the session was waited on before this was raised. */
+    readonly waitedMs: number;
+    /** Always true: a station unreachable now may answer on a later attempt. */
+    readonly retryable = true;
+    constructor(
+    /** The station whose session did not connect. */
+    stationSn: string, 
+    /** How long the session was waited on before this was raised. */
+    waitedMs: number, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * A live stream was refused: the station is already serving another of its cameras to a viewer.
  *

package/dist/index.js

@@ -2556,6 +2556,28 @@ var CameraDisabledError = class extends Error {
     this.name = "CameraDisabledError";
   }
 };
+var StationKeyUnavailableError = class extends Error {
+  stationSn;
+  /** Always true: the negotiation is per connection, so a later one may still produce a key. */
+  retryable = true;
+  constructor(stationSn, options) {
+    super(`station ${stationSn} did not provide its session key, so nothing that requires one could be sent`, options);
+    this.stationSn = stationSn;
+    this.name = "StationKeyUnavailableError";
+  }
+};
+var StationUnreachableError = class extends Error {
+  stationSn;
+  waitedMs;
+  /** Always true: a station unreachable now may answer on a later attempt. */
+  retryable = true;
+  constructor(stationSn, waitedMs, options) {
+    super(`station ${stationSn}'s P2P session did not connect within ${waitedMs}ms, so nothing could be sent to it`, options);
+    this.stationSn = stationSn;
+    this.waitedMs = waitedMs;
+    this.name = "StationUnreachableError";
+  }
+};
 var StationBusyError = class extends Error {
   servingChannel;
   /** Always true: the station is busy now, and stops being busy when the other stream is released. */
@@ -14201,19 +14223,27 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
    * cameras from that second group streamed normally at level-1 — including one of the same firmware as an
    * own-session camera that delivered no video at all for a reason of its own. An expired grace therefore
    * separates nothing on this path, and a start failure on such a session is not evidence about it.
+   *
+   * Every `false` answer carries a `level2-unavailable` trace naming its reason, wherever the wait ended: a
+   * `terminal` outcome is the one already stated where the negotiation concluded, since that is where the
+   * cipher and the cause are known, and re-stating it here would double every settled negotiation.
    */
   async awaitLevel2Key(graceMs, graceFrom = "call") {
-    if (this.closed)
+    if (this.closed) {
+      this.trace({ phase: "level2-unavailable", reason: "session-closed" });
       return false;
+    }
     if (this.level2Key)
       return true;
-    if (!this.level2Pending)
+    if (!this.level2Pending) {
+      this.trace({ phase: "level2-unavailable", reason: "not-negotiating" });
       return false;
+    }
     const since = graceFrom === "call" ? Date.now() : this.connectedAtMs ?? Date.now();
     const remaining = graceMs - (Date.now() - since);
     if (remaining <= 0) {
       this.logger.debug(`[p2p] ${this.cfg.stationSn} no level-2 key and its ${graceMs}ms grace has elapsed`);
-      this.trace({ phase: "level2-absent", waitedMs: graceMs });
+      this.trace({ phase: "level2-unavailable", reason: "grace-elapsed", waitedMs: graceMs });
       return false;
     }
     this.logger.debug(`[p2p] ${this.cfg.stationSn} waiting up to ${remaining}ms for the level-2 key`);
@@ -14239,10 +14269,12 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
     });
     if (outcome === "timeout") {
       this.logger.debug(`[p2p] ${this.cfg.stationSn} level-2 key did not arrive within its grace`);
+      this.trace({ phase: "level2-unavailable", reason: "grace-elapsed", waitedMs: remaining });
     } else if (outcome === "terminal") {
       this.logger.debug(`[p2p] ${this.cfg.stationSn} level-2 negotiation concluded without a key`);
     } else if (outcome === "closed") {
       this.logger.debug(`[p2p] ${this.cfg.stationSn} session closed before the level-2 key arrived`);
+      this.trace({ phase: "level2-unavailable", reason: "session-closed" });
     }
     return outcome === "key";
   }
@@ -14293,6 +14325,7 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
     this.level2Negotiating = true;
     const generation = this.connectionGeneration;
     const cipherId = gatewayInfoCipherId(gwPayload);
+    this.trace({ phase: "level2-negotiating", cipherId });
     void (async () => {
       try {
         const eccPrivHex = await this.cfg.resolveCipherKey?.(cipherId);
@@ -14300,11 +14333,13 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
           return;
         if (!eccPrivHex) {
           this.logger.debug(`[p2p] ${this.cfg.stationSn} no ECC key for cipher_id ${cipherId}`);
+          this.trace({ phase: "level2-unavailable", reason: "no-cipher-key", cipherId });
           this.settleLevel2();
           return;
         }
         const key = deriveLevel2KeyFromGatewayInfo(gwPayload, eccPrivHex);
         if (!key) {
+          this.trace({ phase: "level2-unavailable", reason: "derivation-failed", cipherId });
           this.settleLevel2();
           this.emit("error", new Error(`level-2 key derivation failed (cipher_id ${cipherId})`));
           return;
@@ -14316,6 +14351,7 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
       } catch (e) {
         if (this.closed || generation !== this.connectionGeneration)
           return;
+        this.trace({ phase: "level2-unavailable", reason: "derivation-failed", cipherId });
         this.settleLevel2();
         this.emit("error", e instanceof Error ? e : new Error(String(e)));
       }
@@ -16381,10 +16417,12 @@ var LiveStream = class extends EventEmitter3 {
       if (!this.listening || this.kaTimer)
         return;
       if (this.opts.reassertWanted?.() === false) {
+        this.trace({ phase: "channel-silent", silentMs: stallMs, outcome: "declined" });
         this.logger.debug(`[live ch${this.channel}] no own media for ${stallMs}ms, and its owner does not want this channel re-asserted \u2014 staying quiet`);
         this.armStallWatch();
         return;
       }
+      this.trace({ phase: "channel-silent", silentMs: stallMs, outcome: "reasserted" });
       this.logger.debug(`[live ch${this.channel}] no own media for ${stallMs}ms \u2014 re-asserting this camera's channel`);
       this.sendStart();
       this.kaTimer = setInterval(() => this.sendStart(), keepAliveMs);
@@ -16605,10 +16643,12 @@ async function captureSnapshotFromShared(source, opts = {}) {
   const timeoutMs = opts.timeoutMs ?? 2e4;
   const collectMs = opts.collectMs ?? 1500;
   const skip = opts.skipKeyframes ?? 1;
+  opts.signal?.throwIfAborted();
   const consumer = source.attach();
   const primed = consumer.primed;
+  let burst;
   try {
-    const burst = await new Promise((resolve, reject) => {
+    burst = await new Promise((resolve, reject) => {
       const bufs = [];
       let sets = source.parameterSets;
       let codec = "h264";
@@ -16643,6 +16683,10 @@ async function captureSnapshotFromShared(source, opts = {}) {
         cleanup();
         reject(new LiveSnapshotUnavailableError("source-failed", `source ended before a keyframe (state: ${source.state})`));
       };
+      const onAbandoned = () => {
+        cleanup();
+        reject(opts.signal?.reason);
+      };
       const cleanup = () => {
         clearTimeout(timer);
         if (settle)
@@ -16650,19 +16694,21 @@ async function captureSnapshotFromShared(source, opts = {}) {
         consumer.off("video", onVideo);
         consumer.off("error", onError);
         consumer.off("stop", onStop);
+        opts.signal?.removeEventListener("abort", onAbandoned);
       };
       consumer.on("video", onVideo);
       consumer.on("error", onError);
       consumer.on("stop", onStop);
-    });
-    return await annexbToJpeg(primeForDecode(burst.h264, burst.sets, burst.codec), {
-      logger: opts.logger ?? noopLogger,
-      level: opts.ffmpegLevel,
-      executable: opts.ffmpegPath
+      opts.signal?.addEventListener("abort", onAbandoned, { once: true });
     });
   } finally {
     consumer.detach();
   }
+  return annexbToJpeg(primeForDecode(burst.h264, burst.sets, burst.codec), {
+    logger: opts.logger ?? noopLogger,
+    level: opts.ffmpegLevel,
+    executable: opts.ffmpegPath
+  });
 }
 async function recordClip(session, seconds, opts = {}) {
   const timeoutMs = opts.timeoutMs ?? 2e4;
@@ -18869,6 +18915,11 @@ function abortable(work, signal) {
 }
 var LEVEL2_GRACE_MS = 25e3;
 var LEVEL2_SETTLE_MS = 8e3;
+var P2P_STATION_WAITS = {
+  connect: CONNECT_WAIT_MS,
+  level2Grace: LEVEL2_GRACE_MS,
+  level2Settle: LEVEL2_SETTLE_MS
+};
 var RTSP_URL_READ_TIMEOUT_MS = 12e3;
 var SHARED_LIVE_OPT_KEYS = [
   "eccPrivateKey",
@@ -18920,6 +18971,14 @@ var P2PCommandRouter = class _P2PCommandRouter {
     }
     return normalized;
   }
+  /**
+   * Emit a live trace under a station session's handle, for work this router does ON that session before
+   * the session itself records anything — reaching the station, and resolving what a device is on it. Same
+   * handle as everything the session goes on to trace, which is what groups one attempt.
+   */
+  traceOnStation(session, trace) {
+    traceLiveStart(this.deps.logger ?? noopLogger, trace, session.traceId);
+  }
   /**
    * Whether this transport stack drives `dev`'s `ff09-*` commands — true when the device has its own
    * usable P2P endpoint (a non-empty `p2p_did`). The command sink asks each stack this to route a
@@ -19060,7 +19119,15 @@ var P2PCommandRouter = class _P2PCommandRouter {
         let ecc;
         try {
           const ciphers = await this.deps.mega.getCiphers([cipherId], adminUserId, stationSn);
-          ecc = ciphers.find((c) => Number(c.cipher_id) === cipherId)?.ecc_private_key ?? ciphers[0]?.ecc_private_key;
+          ecc = ciphers.find((c) => Number(c.cipher_id) === cipherId)?.ecc_private_key;
+          if (ecc === void 0 && ciphers[0]?.ecc_private_key !== void 0) {
+            ecc = ciphers[0].ecc_private_key;
+            this.traceOnStation(session, {
+              phase: "cipher-fallback",
+              cipherId,
+              answeredCipherId: Number(ciphers[0].cipher_id)
+            });
+          }
         } catch (e) {
           this.deps.onError(e instanceof Error ? e : new Error(String(e)));
         }
@@ -19214,12 +19281,12 @@ var P2PCommandRouter = class _P2PCommandRouter {
     return {
       snapshotLive: async (opts) => {
         const source = await this.sharedLiveSourceFor(sn, opts ?? {});
-        return abortable(captureSnapshotFromShared(source, {
+        return captureSnapshotFromShared(source, {
           ...opts,
           logger: this.deps.logger ?? noopLogger,
           ffmpegLevel: this.deps.ffmpegLogLevel,
           ffmpegPath: this.deps.ffmpegPath
-        }), opts?.signal);
+        });
       },
       live: async (opts) => {
         const source = await this.sharedLiveSourceFor(sn, opts);
@@ -19691,9 +19758,9 @@ var P2PCommandRouter = class _P2PCommandRouter {
           s.sendStringPayloadCommand(P2P_ENVELOPE.CONTROL_PAYLOAD, json, ch);
           return Promise.resolve();
         },
-        l2: async ({ session: s, channel: ch }) => {
+        l2: async ({ session: s, channel: ch, parentSn }) => {
           if (!await s.awaitLevel2Key(LEVEL2_GRACE_MS, "call")) {
-            throw new Error(`level-2 key not ready for ${sn} \u2014 cannot query`);
+            throw new StationKeyUnavailableError(parentSn);
           }
           s.sendRawLevel2(json, ch, P2P_ENVELOPE.CONTROL_PAYLOAD);
         }
@@ -19860,15 +19927,28 @@ var P2PCommandRouter = class _P2PCommandRouter {
     }
     this.manager.bumpCommand(parentSn);
     const channel = typeof raw.device_channel === "number" ? raw.device_channel : 0;
-    const accountId = raw.member?.admin_user_id ?? this.deps.mega.auth?.userId ?? "";
+    const stationAdminId = raw.member?.admin_user_id;
+    const accountId = stationAdminId ?? this.deps.mega.auth?.userId ?? "";
     const t0 = Date.now();
-    while (!session.isConnected && Date.now() - t0 < CONNECT_WAIT_MS) {
-      opts.signal?.throwIfAborted();
-      await sleep2(200);
+    let waitedMs = 0;
+    if (!session.isConnected) {
+      this.traceOnStation(session, { phase: "session-connect-wait", waitMs: CONNECT_WAIT_MS });
+      while (!session.isConnected && Date.now() - t0 < CONNECT_WAIT_MS) {
+        opts.signal?.throwIfAborted();
+        await sleep2(200);
+      }
+      waitedMs = Date.now() - t0;
+      this.traceOnStation(session, session.isConnected ? { phase: "session-connected", waitedMs } : { phase: "session-unreachable", waitedMs });
     }
     opts.signal?.throwIfAborted();
     if (!session.isConnected)
-      throw new Error(`P2P session for ${parentSn} did not connect`);
+      throw new StationUnreachableError(parentSn, waitedMs);
+    this.traceOnStation(session, {
+      phase: "station-resolved",
+      topology: homeBaseAttached ? "attached" : "own",
+      channel,
+      stationAdmin: typeof stationAdminId !== "string" ? "unstated" : stationAdminId === this.deps.mega.auth?.userId ? "self" : "other"
+    });
     if (opts.waitLevel2) {
       if (opts.waitLevel2 === "settle") {
         await abortable(session.awaitLevel2Key(LEVEL2_SETTLE_MS, "session"), opts.signal);
@@ -19882,7 +19962,7 @@ var P2PCommandRouter = class _P2PCommandRouter {
         ready = await abortable(session.awaitLevel2Key(LEVEL2_GRACE_MS, "call"), opts.signal);
       }
       if (!ready)
-        throw new Error(`level-2 key not ready for ${parentSn}`);
+        throw new StationKeyUnavailableError(parentSn);
     }
     return { session, parentSn, channel, accountId, homeBaseAttached };
   }
@@ -25397,6 +25477,7 @@ export {
   P256,
   P2PSession,
   P2P_ENVELOPE,
+  P2P_STATION_WAITS,
   PRINTER_CATEGORY_RE,
   PTZ_MEMBERS,
   PowerSource,
@@ -25430,6 +25511,8 @@ export {
   SmartDropPushEvent,
   StateConvergenceError,
   StationBusyError,
+  StationKeyUnavailableError,
+  StationUnreachableError,
   StoredSnapshotUnavailableError,
   StreamingQuality,
   SuctionLevel,