@mega-yfue/eufy-sdk 0.6.0-beta.30 → 0.6.0-beta.32

package/dist/core/contracts.d.ts

@@ -153,8 +153,9 @@ export declare class DeviceChannelUnresolvedError extends Error {
 /**
  * Why {@link MediaProvider.downloadRecording} returned no recording.
  *
- * - `invalid-recording` — the recording name is not one the station could hold.
- * - `key-unavailable` — the key the recording was stored under could not be obtained.
+ * - `invalid-recording` — the recording name is not one the camera's station could hold.
+ * - `key-unavailable` — the station stores the recording sealed and the key it was sealed under could not be
+ *   obtained.
  * - `no-data` — the station sent nothing within the wait.
  * - `incomplete` — the transfer ended before the station's finish frame.
  * - `undecodable` — data arrived but no video frame could be decoded from it.
@@ -170,10 +171,10 @@ export declare class RecordingDownloadError extends Error {
 /**
  * A recording downloaded from the station, as elementary streams.
  *
- * `video` is Annex-B H.264 in decode order, `audio` AAC-LC 16 kHz mono in ADTS framing (absent when the
- * recording carried none that could be decoded). `frames` counts the distinct video sequences emitted.
- * `missingFrames` counts gaps between received sequences and received sequences that yielded no usable
- * picture, including at either end. `durationMs` spans the first to the last emitted picture by the
+ * `video` is Annex-B H.264 or H.265 in decode order, `audio` AAC-LC 16 kHz mono in ADTS framing (absent
+ * when the recording carried none that could be decoded). `frames` counts the distinct video sequences
+ * emitted. `missingFrames` counts gaps between received sequences and received sequences that yielded no
+ * usable picture, including at either end. `durationMs` spans the first to the last emitted picture by the
  * camera's own timestamps; `fps` is derived from those stamps.
  */
 export interface RecordingDownload {
@@ -884,9 +885,11 @@ export interface MediaProvider {
         encoder?: AacEncoder;
     } & SharedSourceHints): Promise<TalkbackHandle>;
     /**
-     * Download one recording the camera's station stored, identified by the recording name and cipher id of
-     * the event. One download runs at a time per station. Rejects with {@link RecordingDownloadError}.
-     * Optional, and absent on a camera whose station's recording download is unverified.
+     * Download one recording the camera's station stored. `recording` names it: the file name the station stores
+     * it under, without the folder or the extension. `cipherId` is the cipher the station names for it, and is not
+     * read on a station that stores its recordings in the clear. One download runs at a time per station. Rejects with
+     * {@link RecordingDownloadError}. Optional, and absent on a camera whose station's recording download is
+     * unverified.
      */
     downloadRecording?(opts: {
         recording: string;

package/dist/index.js

@@ -1609,11 +1609,17 @@ var CONTENDED_SESSION_HINT = "the token was rejected again soon after it was las
 function tokenRejected(code, msg) {
   return code === EufyCloudErrorCode.SESSION_KICKED || /user_id is empty|invalid[^,]*\btoken\b|\btoken\b[^,]*(expired|error|not exist)|kicked|(?:\btoken\b|\bsession\b)[^,]*does not exist|unauthor/i.test(msg ?? "");
 }
+function shardOfDomain(domain) {
+  const m = /-([a-z]{2})(?:[.-]|$)/i.exec(domain);
+  return m ? `${m[1].toLowerCase()}-pr` : void 0;
+}
 var MegaHttpClient = class {
   cfg;
   region;
   /** The host `estimate_domain` answered, persisted with the session. */
   estimatedDomain = "";
+  /** The in-flight (then settled, so cached) RTC-sign shard request from {@link portalShard}. */
+  portalShardInFlight;
   bootstrapDomain;
   sessionKey;
   /** Per-host ECDH session keys for non-mega gateways (e.g. eufylife) keyed by host. */
@@ -1730,13 +1736,36 @@ var MegaHttpClient = class {
     return this.region;
   }
   /**
-   * The shard the RTC signalling signs on: the regional prefix of the estimated domain
-   * (`…-ie-…`/`…-ie.` → `ie-pr`), else {@link regionShard}. The eu/us classification cannot name shards
-   * like `ie-pr`, whose accounts need the IE sign host and cluster.
+   * The shard the estimated domain names (`…-ie-…`/`…-ie.` → `ie-pr`), else {@link regionShard}. The
+   * eu/us classification cannot name shards like `ie-pr`.
    */
   get rtcShard() {
-    const m = /-([a-z]{2})(?:[.-]|$)/i.exec(this.estimatedDomain);
-    return m ? `${m[1].toLowerCase()}-pr` : this.region;
+    return shardOfDomain(this.estimatedDomain) ?? this.region;
+  }
+  /**
+   * The shard the RTC signalling signs on, from `estimate_domain` asked with the portal's WEB identity
+   * (`Model-Type: WEB`, `App-Name: eufy_mega`) — the identity the sign itself is sent with, which can name
+   * a different shard than the PHONE identity does for one account. The in-flight request is shared by
+   * concurrent first callers, and once it settles to a shard the resolved promise is the cache; a call
+   * that fails or names no shard answers {@link rtcShard}, clears the field and is asked again next time.
+   */
+  async portalShard() {
+    return this.portalShardInFlight ??= this.fetchPortalShard();
+  }
+  async fetchPortalShard() {
+    try {
+      const res = await this.estimateDomainRequest({ "Model-Type": "WEB", "App-Name": "eufy_mega" });
+      const domain = res.data?.data?.domain;
+      const shard = typeof domain === "string" ? shardOfDomain(domain) : void 0;
+      if (shard) {
+        this.logger.debug("[mega] portal shard:", shard);
+        return shard;
+      }
+    } catch (e) {
+      this.logger.debug("[mega] portal estimate_domain failed:", e instanceof Error ? e.message : String(e));
+    }
+    this.portalShardInFlight = void 0;
+    return this.rtcShard;
   }
   /**
    * The credentials the RTC signalling needs; `undefined` while logged out. The sign is refused
@@ -1833,13 +1862,13 @@ var MegaHttpClient = class {
     });
     return { status: res.status, data: parseMaybeJson(await res.text()) };
   }
+  /** POST `estimate_domain` with the given identity headers. */
+  estimateDomainRequest(headers) {
+    return this.httpPost(`https://mega-${this.region}.eufy.com/passport/estimate_domain`, { ab: this.cfg.countryCode.toLowerCase(), mode: 1 }, { ...headers, "content-type": "application/json" });
+  }
   /** Step 1: discover the account's region shard (and the bootstrap host). */
   async estimateDomain() {
-    const url = `https://mega-${this.region}.eufy.com/passport/estimate_domain`;
-    const res = await this.httpPost(url, { ab: this.cfg.countryCode.toLowerCase(), mode: 1 }, {
-      ...this.baseHeaders(),
-      "content-type": "application/json"
-    });
+    const res = await this.estimateDomainRequest(this.baseHeaders());
     this.logger.debug("[mega] estimate_domain raw:", JSON.stringify(res.data).slice(0, 400));
     const env = res.data;
     const d = env?.data ?? {};
@@ -18951,15 +18980,19 @@ var VideoFrameDecoder = class {
 var STATION_CHUNK_BYTES = 64e3;
 var AccessUnitAssembler = class {
   onDropped;
+  chunkBytes;
   open;
   droppedUnits = 0;
   /**
    * @param onDropped called for each incomplete unit discarded, with what had arrived, how many frames it
    * arrived in, and how many this assembler has dropped in total — a running count, so no caller keeps
    * its own.
+   * @param chunkBytes the payload size the station fills a frame to before continuing a unit in the next. A
+   * unit is held while its latest frame declares exactly this. {@link STATION_CHUNK_BYTES} when omitted.
    */
-  constructor(onDropped) {
+  constructor(onDropped, chunkBytes = STATION_CHUNK_BYTES) {
     this.onDropped = onDropped;
+    this.chunkBytes = chunkBytes;
   }
   /**
    * Feed one raw `CMD_VIDEO_FRAME` payload; returns the access units it completed — none while a unit is
@@ -18978,7 +19011,7 @@ var AccessUnitAssembler = class {
       this.discard();
       return [];
     }
-    const full = header.payloadLength === STATION_CHUNK_BYTES;
+    const full = header.payloadLength === this.chunkBytes;
     const open2 = this.open;
     if (open2 && sameUnit(open2.header, header) && !beginsAccessUnit(body)) {
       open2.chunks.push(body);
@@ -19992,16 +20025,31 @@ function annexbToJpeg(annexb, spawn2) {
 var RECORDING_DATA_TYPE = 3;
 var VIDEO_HEADER_LEN2 = 22;
 var AUDIO_CODEC_AAC_LC = 0;
-var FINISH_CHANNEL = 0;
 var FIRST_FRAME_WAIT_MS = 2e4;
 var IDLE_END_MS = 15e3;
 var DEFAULT_TRANSFER_MS = 12e4;
 var MAX_TRANSFER_BYTES = 32 * 1024 * 1024;
+function cameraFolder(channel) {
+  if (!Number.isInteger(channel) || channel < 0 || channel > 99)
+    return void 0;
+  return `Camera${String(channel).padStart(2, "0")}`;
+}
 function homeBase2RecordingPath(channel, recording) {
-  if (!/^(?:h265_)?\d{14}$/.test(recording) || !Number.isInteger(channel) || channel < 0 || channel > 99)
+  const folder = cameraFolder(channel);
+  if (!folder || !/^(?:h265_)?\d{14}$/.test(recording))
+    return void 0;
+  return `/media/mmcblk0p1/${folder}/${recording}.dat`;
+}
+function homeBase3RecordingPath(channel, recording) {
+  const folder = cameraFolder(channel);
+  if (!folder || !/^\d{14}$/.test(recording))
     return void 0;
-  return `/media/mmcblk0p1/Camera${String(channel).padStart(2, "0")}/${recording}.dat`;
+  return `/zx/emmcdata/${folder}/${recording.slice(0, 6)}/${recording}/${recording}.zxvideo`;
 }
+var RECORDING_STATIONS = /* @__PURE__ */ new Map([
+  ["T8010", { path: homeBase2RecordingPath, sealed: true, finishChannel: 0, chunkBytes: STATION_CHUNK_BYTES }],
+  ["T8030", { path: homeBase3RecordingPath, sealed: false, finishChannel: STATION_CHANNEL3, chunkBytes: 4e5 }]
+]);
 function receiveRecording(session, request) {
   let resolveFrames;
   let rejectFrames;
@@ -20045,7 +20093,7 @@ function receiveRecording(session, request) {
   };
   const onData = (frame) => {
     if (frame.commandId === CommandType.CMD_DOWNLOAD_FINISH) {
-      if (frame.channel !== request.channel && frame.channel !== FINISH_CHANNEL)
+      if (frame.channel !== request.channel && frame.channel !== request.finishChannel)
         return;
       if (draining)
         incomplete(draining);
@@ -20102,12 +20150,17 @@ function receiveRecording(session, request) {
   }
   return { frames, drained };
 }
-function decodeRecording(frames, eccPrivateKeyHex) {
-  const eccPrivateKey = Buffer.from(eccPrivateKeyHex, "hex");
-  if (eccPrivateKey.length !== 32)
+function clearVideoPayload(raw, header) {
+  const end = VIDEO_HEADER_LEN2 + header.payloadLength;
+  return raw.length >= end ? raw.subarray(VIDEO_HEADER_LEN2, end) : void 0;
+}
+function decodeRecording(frames, station, eccPrivateKeyHex) {
+  const eccPrivateKey = station.sealed ? Buffer.from(eccPrivateKeyHex ?? "", "hex") : void 0;
+  if (eccPrivateKey && eccPrivateKey.length !== 32) {
     throw new RecordingDownloadError("undecodable", "the cipher key is not a P-256 key");
-  const decoder = new VideoFrameDecoder(eccPrivateKey);
-  const assembler = new AccessUnitAssembler();
+  }
+  const decoder = eccPrivateKey && new VideoFrameDecoder(eccPrivateKey);
+  const assembler = new AccessUnitAssembler(void 0, station.chunkBytes);
   const video = [];
   const audio = [];
   const numbers = /* @__PURE__ */ new Set();
@@ -20120,7 +20173,7 @@ function decodeRecording(frames, eccPrivateKeyHex) {
       if (!header)
         continue;
       receivedNumbers.add(header.sequence);
-      const units = assembler.push(raw, (payload) => header.keyframe ? decoder.decodeFrame(payload)?.h264 : payload.length >= VIDEO_HEADER_LEN2 + header.payloadLength ? payload.subarray(VIDEO_HEADER_LEN2, VIDEO_HEADER_LEN2 + header.payloadLength) : void 0);
+      const units = assembler.push(raw, (payload) => decoder && header.keyframe ? decoder.decodeFrame(payload)?.h264 : clearVideoPayload(payload, header));
       for (const unit of units) {
         video.push(unit.data);
         numbers.add(header.sequence);
@@ -20129,10 +20182,10 @@ function decodeRecording(frames, eccPrivateKeyHex) {
         lastStamp = stamp;
       }
     } else if (commandId === CommandType.CMD_AUDIO_FRAME) {
-      const mediaKey = decoder.currentMediaKey;
-      if (!mediaKey || raw[5] !== AUDIO_CODEC_AAC_LC)
+      if (raw[5] !== AUDIO_CODEC_AAC_LC)
         continue;
-      const aac = openSealedAudio(raw, mediaKey);
+      const mediaKey = decoder?.currentMediaKey;
+      const aac = decoder ? mediaKey && openSealedAudio(raw, mediaKey) : raw.subarray(AUDIO_HEADER_LEN);
       if (aac?.length)
         audio.push(aac);
     }
@@ -22864,7 +22917,8 @@ var P2PCommandRouter = class _P2PCommandRouter {
    * start has no level-1 form for.
    */
   mediaProviderFor(sn) {
-    const recordings = this.downloadsRecordings(sn) ? { downloadRecording: (opts) => this.downloadRecording(sn, opts) } : {};
+    const station = this.recordingStationFor(sn);
+    const recordings = station ? { downloadRecording: (opts) => this.downloadRecording(sn, station, opts) } : {};
     return {
       ...recordings,
       snapshotLive: async (opts) => {
@@ -22906,29 +22960,32 @@ var P2PCommandRouter = class _P2PCommandRouter {
     };
   }
   /**
-   * Whether `sn` is a camera attached to a HomeBase 2 (T8010), the one station whose recording path layout
-   * and frame formats are confirmed.
+   * The {@link RecordingStation} of the station `sn` is attached to, when `sn` is a camera attached to a
+   * station with an entry in {@link RECORDING_STATIONS}. A standalone device, or a camera on any other
+   * station, answers `undefined`.
    */
-  downloadsRecordings(sn) {
+  recordingStationFor(sn) {
     const dev = this.recordFor(sn);
     if (!dev)
-      return false;
+      return void 0;
     const parentSn = stationOf(dev);
-    return parentSn !== sn && this.recordFor(parentSn)?.model === "T8010";
+    if (parentSn === sn)
+      return void 0;
+    return RECORDING_STATIONS.get(this.recordFor(parentSn)?.model ?? "");
   }
   /**
-   * Download one recording a HomeBase 2 holds for an attached camera, then decode it
-   * ({@link decodeRecording}). Downloads queue per station: the station streams one recording at a time
-   * on the camera's channel, so a download starts only once the previous one has drained
-   * ({@link RecordingTransfer.drained}), even when that one's caller already has its answer. An abort
-   * while waiting rejects without sending anything; an abort mid-transfer rejects at once and the station's
-   * turn is held until the transfer drains.
+   * Download one recording `station` holds for the attached camera `sn`, then decode it
+   * ({@link decodeRecording}). `station` is the entry {@link mediaProviderFor} bound. Downloads queue per
+   * station: the station streams one recording at a time on the camera's channel, so a download starts only
+   * once the previous one has drained ({@link RecordingTransfer.drained}), even when that one's caller already
+   * has its answer. An abort while waiting rejects without sending anything; an abort mid-transfer rejects at
+   * once and the station's turn is held until the transfer drains.
    */
-  async downloadRecording(sn, opts) {
+  async downloadRecording(sn, station, opts) {
     opts.signal?.throwIfAborted();
     const parentSn = this.stationKeyOf(sn);
     const previous = this.recordingDownloads.get(parentSn) ?? Promise.resolve();
-    const started = this.waitTurn(previous, opts.signal).then(() => this.startRecordingDownload(sn, opts));
+    const started = this.waitTurn(previous, opts.signal).then(() => this.startRecordingDownload(sn, station, opts));
     const turn = Promise.allSettled([previous, started.then((t) => t.drained)]).then(() => {
       if (this.recordingDownloads.get(parentSn) === turn)
         this.recordingDownloads.delete(parentSn);
@@ -22942,25 +22999,32 @@ var P2PCommandRouter = class _P2PCommandRouter {
   }
   /**
    * Start one recording download, once the station's previous download has drained: the decoded recording,
-   * and when the station is done sending it.
+   * and when the station is done sending it. The path is `station.path(channel, opts.recording)`, and a name
+   * it refuses rejects `invalid-recording` before anything is sent. On a sealed station the cipher's ECC key
+   * is looked up, and its absence rejects `key-unavailable` before anything is sent. A station in the clear
+   * reads no cipher, and `opts.cipherId` is not read.
    */
-  async startRecordingDownload(sn, opts) {
+  async startRecordingDownload(sn, station, opts) {
     const { session, parentSn, channel, accountId } = await this.resolveSession(sn, { signal: opts.signal });
-    const path = homeBase2RecordingPath(channel, opts.recording);
+    const path = station.path(channel, opts.recording);
     if (!path)
       throw new RecordingDownloadError("invalid-recording", `no recording named ${opts.recording}`);
-    const eccKey = (await this.cipherKeysFor(session, opts.cipherId, accountId, parentSn))?.ecc;
-    if (!eccKey) {
+    const eccKey = station.sealed ? (await this.cipherKeysFor(session, opts.cipherId, accountId, parentSn))?.ecc : void 0;
+    if (station.sealed && !eccKey) {
       throw new RecordingDownloadError("key-unavailable", `cipher ${opts.cipherId} could not be obtained`);
     }
     const transfer = receiveRecording(session, {
       path,
       accountId,
       channel,
+      finishChannel: station.finishChannel,
       timeoutMs: opts.timeoutMs,
       signal: opts.signal
     });
-    return { recording: transfer.frames.then((frames) => decodeRecording(frames, eccKey)), drained: transfer.drained };
+    return {
+      recording: transfer.frames.then((frames) => decodeRecording(frames, station, eccKey)),
+      drained: transfer.drained
+    };
   }
   /**
    * Open a {@link Talkback} on a device's camera channel.
@@ -25692,6 +25756,8 @@ var RtcCommandRouter = class {
   warm = /* @__PURE__ */ new Map();
   callSources = /* @__PURE__ */ new Map();
   lastTransaction = 0;
+  /** The latest shard each `call` source resolved, read by its `makeStream` (see {@link callMediaProviderFor}). */
+  callShards = /* @__PURE__ */ new Map();
   constructor(deps) {
     this.deps = deps;
   }
@@ -25818,7 +25884,13 @@ var RtcCommandRouter = class {
       views
     };
   }
-  /** Share a dedicated-call source and its consumer operations under one route key. */
+  /**
+   * Share a dedicated-call source and its consumer operations under one route key.
+   *
+   * `SharedLiveSource` calls `makeStream` synchronously, so the shard cannot be awaited inside it. Each
+   * async entry point resolves the shard and records it in {@link callShards} before touching the source;
+   * `makeStream` reads the latest recorded value.
+   */
   callMediaProviderFor(route, key, makeStream, recordError, warmTimeoutMs) {
     const sourceFor = (opts = {}) => {
       opts.signal?.throwIfAborted();
@@ -25832,7 +25904,7 @@ var RtcCommandRouter = class {
             if (!identity)
               throw new Error(`rtc: not logged in, cannot call ${route.stationSn}`);
             const accountId = route.adminUserId || identity.userId;
-            return makeStream(this.newSession(route, accountId, identity), accountId, view);
+            return makeStream(this.newSession(route, accountId, identity, this.callShards.get(key)), accountId, view);
           },
           label: sourceKey,
           logger: this.deps.logger,
@@ -25844,14 +25916,26 @@ var RtcCommandRouter = class {
       }
       return source;
     };
+    const resolveShard = async () => {
+      this.callShards.set(key, await this.deps.shard(route));
+    };
     return {
-      live: async (opts) => attachUnlessAborted(sourceFor(opts), opts?.signal),
-      openReadable: async (opts) => openReadableFromConsumer(attachUnlessAborted(sourceFor(opts), opts?.signal), opts),
-      snapshotLive: async (opts) => captureSnapshotFromShared(sourceFor(opts), {
-        ...opts,
-        logger: this.deps.logger,
-        ffmpegPath: this.deps.ffmpegPath
-      }),
+      live: async (opts) => {
+        await resolveShard();
+        return attachUnlessAborted(sourceFor(opts), opts?.signal);
+      },
+      openReadable: async (opts) => {
+        await resolveShard();
+        return openReadableFromConsumer(attachUnlessAborted(sourceFor(opts), opts?.signal), opts);
+      },
+      snapshotLive: async (opts) => {
+        await resolveShard();
+        return captureSnapshotFromShared(sourceFor(opts), {
+          ...opts,
+          logger: this.deps.logger,
+          ffmpegPath: this.deps.ffmpegPath
+        });
+      },
       record: async () => {
         throw new Error(recordError);
       }
@@ -25866,6 +25950,7 @@ var RtcCommandRouter = class {
       this.callSources.delete(sn);
       src.dispose();
     }
+    this.callShards.clear();
     for (const [sn, live] of this.lives) {
       this.lives.delete(sn);
       live.source.dispose();
@@ -26059,31 +26144,50 @@ var RtcCommandRouter = class {
       }
     });
   }
-  newSession(route, adminUserId, identity) {
+  newSession(route, adminUserId, identity, shard) {
     return (this.deps.createSession ?? ((o) => new RtcSession(o)))({
       authToken: identity.authToken,
       gtoken: identity.gtoken,
       stationSn: route.stationSn,
       adminUserId,
-      shard: this.deps.shard(),
+      shard,
       country: this.deps.country ?? "US",
       logger: this.deps.logger,
       signalingMode: route.signalingMode,
       peer: { logger: this.deps.logger, iceTransportPolicy: route.iceTransportPolicy, mediaTrack: route.mediaTrack }
     });
   }
+  /** A connected session for `sn` to reuse, or undefined (dropping a dead one). */
+  async reusable(sn) {
+    const st = this.sessions.get(sn);
+    if (!st)
+      return void 0;
+    await st.ready;
+    if (st.session.isConnected) {
+      this.touch(sn, st);
+      return st;
+    }
+    this.drop(sn, st);
+    return void 0;
+  }
+  /**
+   * Get or open the station's session. A connected session is reused before the shard is awaited, so a
+   * command on an already-connected station never waits on the unauthenticated `estimate_domain` round
+   * trip — only the create path awaits it. After the await the map is re-checked, with no `await` between
+   * the lookup and `this.sessions.set`, so concurrent creators still share one session.
+   */
   async stationSession(route, adminUserId, identity) {
     const sn = route.stationSn;
-    const existing = this.sessions.get(sn);
-    if (existing) {
-      await existing.ready;
-      if (existing.session.isConnected) {
-        this.touch(sn, existing);
-        return existing;
-      }
-      this.drop(sn, existing);
-    }
-    const session = this.newSession(route, adminUserId, identity);
+    const reused = await this.reusable(sn);
+    if (reused)
+      return reused;
+    const shard = await this.deps.shard(route);
+    if (this.sessions.has(sn)) {
+      const again = await this.reusable(sn);
+      if (again)
+        return again;
+    }
+    const session = this.newSession(route, adminUserId, identity, shard);
     const ready = this.bringUp(sn, session);
     const st = { session, seg: new SegmentCounter(), ready, queue: Promise.resolve(), leases: 0 };
     session.on("error", (e) => this.deps.onError?.(e));
@@ -29733,7 +29837,7 @@ var EufyMega = class _EufyMega extends EventEmitter14 {
     });
     this.rtc = new RtcCommandRouter({
       identity: () => this.mega.rtcIdentity(),
-      shard: () => this.mega.rtcShard,
+      shard: (route) => route.mediaTrack ? this.mega.rtcShard : this.mega.portalShard(),
       country: opts.countryCode,
       logger: opts.logger,
       ffmpegPath: opts.ffmpegPath,