@mega-yfue/eufy-sdk 0.2.0-beta.1 → 0.2.0-beta.3

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. */
@@ -6890,6 +6912,16 @@ var KEYPAD = {
 // dist/model/capabilities/arming.js
 var STATION_CHANNEL2 = 255;
 var ArmingMode = {
+  /** Armed — full protection, nobody home (wire value 0). */
+  away: "away",
+  /** Armed for occupancy — reduced/perimeter protection while home (wire value 1). */
+  home: "home",
+  /** Custom 1 — a user-defined posture configured in the app (wire value 3). */
+  custom1: "custom1",
+  /** Disarmed — no alarms; sensors still report state (wire value 63). */
+  disarmed: "disarmed"
+};
+var AlarmDelayMode = {
   /** Armed — full protection, nobody home (wire value 0). */
   away: "away",
   /** Armed for occupancy — reduced/perimeter protection while home (wire value 1). */
@@ -6905,10 +6937,11 @@ var ARMING_CMD = {
    * mValue3:0, `payload:{mode_type:<int>, user_name:<string>}`.
    *
    * ⚠️ Only 3 of the 9 modes were exercised in that capture — `mode_type` 0 (away), 63 (disarmed), 1
-   * (home), all confirmed byte-exact, and those three are the whole of {@link ArmingMode}. Re-confirmed
-   * live 2026-08-05: each reported its own MODE_SWITCH push within ~5s of the write. The remaining six are
-   * named by the app but never observed leaving it, so this capability reads them and refuses to send
-   * them. See `ARMING_MODE_WIRE` for the per-value breakdown.
+   * (home), all confirmed byte-exact. Re-confirmed live 2026-08-05: each reported its own MODE_SWITCH push
+   * within ~5s of the write. `custom1` 3 joined {@link ArmingMode} on a live confirmation rather than a
+   * capture, making four settable in total. The remaining five are named by the app but never observed
+   * leaving it, so this capability reads them and refuses to send them. See `ARMING_MODE_WIRE` for the
+   * per-value breakdown.
    */
   SET_ARMING: 1224,
   /**
@@ -6944,7 +6977,6 @@ var ARMING_MODE_WIRE = {
   schedule: 2,
   // ⚠️ reportable, NOT settable — see the doc comment above
   custom1: 3,
-  // ⚠️ reportable, NOT settable — see the doc comment above
   custom2: 4,
   // ⚠️ reportable, NOT settable — see the doc comment above
   custom3: 5,
@@ -6987,9 +7019,9 @@ function alarmDelayCommand(mode, config, ctx) {
 var ARMING_MEMBERS = {
   /**
    * The one member whose write domain is NARROWER than its read: `enumValues` names all nine modes a
-   * station can report, and the argument's `values` publishes only the three whose wire was captured. That
-   * argument IS the domain the derived setter enforces and the refusal names, so an uncaptured mode is
-   * refused by naming the three that work — nine labels for the read and three for the write, off one
+   * station can report, and the argument's `values` publishes only the four whose write is confirmed. That
+   * argument IS the domain the derived setter enforces and the refusal names, so an unconfirmed mode is
+   * refused by naming the four that work — nine labels for the read and four for the write, off one
    * declaration.
    *
    * `armingCommand` may also throw synchronously (missing account identity) and `bindMembers` turns that
@@ -7010,7 +7042,7 @@ var ARMING_MEMBERS = {
     enumValues: ARMING_MODE_LABELS,
     provenance: "verified",
     args: [{ name: "mode", kind: "enum", values: SETTABLE_MODES }],
-    description: "Guard mode (verified: param 1224 = GUARD_MODE, read/write mechanism confirmed). Reads all 9 modes the app defines; SETS only the 3 whose write is wire-captured (away/home/disarmed) \u2014 schedule/custom1/custom2/custom3/off/geo are named by the app but no capture shows one being sent, so they are refused rather than guessed; see ARMING_MODE_WIRE in arming.ts for the breakdown.",
+    description: "Guard mode (verified: param 1224 = GUARD_MODE, read/write mechanism confirmed). Reads all 9 modes the app defines; SETS only the 4 whose write is confirmed (away/home/custom1/disarmed) \u2014 schedule/custom2/custom3/off/geo are named by the app but no capture shows one being sent, so they are refused rather than guessed; see ARMING_MODE_WIRE in arming.ts for the breakdown.",
     observation: {
       event: "armingModeChanged",
       reflects: (value) => ({ param: ARMING_CMD.SET_ARMING, expected: ARMING_MODE_WIRE[armingModeOf(value)] }),
@@ -7031,9 +7063,10 @@ var ARMING_MEMBERS = {
    * this mode — there is no known GET to fetch it automatically, and a wrong guess here can silently
    * misconfigure which sensors arm/trigger for real.
    *
-   * Takes {@link ArmingMode}, so a delay can only be configured for a mode whose `mode_id` integer is
-   * captured. The frame carries that same integer, so a schedule/custom mode would be the identical guess
-   * `setMode` refuses.
+   * Takes {@link AlarmDelayMode}, not {@link ArmingMode}: a delay is configurable only for a mode whose
+   * integer is captured on THIS command, and `custom1` is confirmed on cmd 1224 only. The frame carries
+   * that integer in `mode_id` with no runtime validation and no readback, so a mode outside this union
+   * would be the same unverified guess `setMode` refuses.
    */
   setAlarmDelayConfig: method(({ ctx, sink }) => (mode, config) => {
     try {
@@ -14190,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`);
@@ -14228,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";
   }
@@ -14282,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);
@@ -14289,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;
@@ -14305,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)));
       }
@@ -18858,6 +18905,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",
@@ -18909,6 +18961,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
@@ -19049,7 +19109,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)));
         }
@@ -19680,9 +19748,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);
         }
@@ -19849,15 +19917,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);
@@ -19871,7 +19952,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 };
   }
@@ -25312,6 +25393,7 @@ export {
   AUDIO_MEMBERS,
   AccessUnitAssembler,
   AiDetectType,
+  AlarmDelayMode,
   ArmingMode,
   BATTERY_MEMBERS,
   BIZ_CHANNEL,
@@ -25385,6 +25467,7 @@ export {
   P256,
   P2PSession,
   P2P_ENVELOPE,
+  P2P_STATION_WAITS,
   PRINTER_CATEGORY_RE,
   PTZ_MEMBERS,
   PowerSource,
@@ -25418,6 +25501,8 @@ export {
   SmartDropPushEvent,
   StateConvergenceError,
   StationBusyError,
+  StationKeyUnavailableError,
+  StationUnreachableError,
   StoredSnapshotUnavailableError,
   StreamingQuality,
   SuctionLevel,