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

package/dist/transport/http/mega-client.d.ts

@@ -212,6 +212,8 @@ export declare class MegaHttpClient {
     private region;
     /** The host `estimate_domain` answered, persisted with the session. */
     private estimatedDomain;
+    /** The in-flight (then settled, so cached) RTC-sign shard request from {@link portalShard}. */
+    private portalShardInFlight?;
     private bootstrapDomain?;
     private sessionKey?;
     /** Per-host ECDH session keys for non-mega gateways (e.g. eufylife) keyed by host. */
@@ -283,11 +285,19 @@ export declare class MegaHttpClient {
     /** The active region shard (e.g. `"eu-pr"`, `"us-pr"`), set after {@link login} or a region override. */
     get regionShard(): RegionShard;
     /**
-     * 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(): string;
+    /**
+     * 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.
+     */
+    portalShard(): Promise<string>;
+    private fetchPortalShard;
     /**
      * The credentials the RTC signalling needs; `undefined` while logged out. The sign is refused
      * ("gtoken not equal userid") unless its gtoken is the one every authed HTTP call carries.
@@ -334,6 +344,8 @@ export declare class MegaHttpClient {
      * raw text. Never throws on HTTP status (the callers classify the envelope themselves). 20s timeout.
      */
     private httpPost;
+    /** POST `estimate_domain` with the given identity headers. */
+    private estimateDomainRequest;
     /** Step 1: discover the account's region shard (and the bootstrap host). */
     estimateDomain(): Promise<void>;
     /**

package/dist/transport/p2p/command-router.d.ts

@@ -314,24 +314,28 @@ export declare class P2PCommandRouter {
      */
     mediaProviderFor(sn: string): MediaProvider;
     /**
-     * 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`.
      */
-    private downloadsRecordings;
+    private recordingStationFor;
     /**
-     * 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.
      */
     private downloadRecording;
     /** Resolve once `previous` settles, or reject as soon as `signal` aborts. */
     private waitTurn;
     /**
      * 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.
      */
     private startRecordingDownload;
     /**

package/dist/transport/p2p/recording-download.d.ts

@@ -1,13 +1,14 @@
 /**
- * Download of a recording held on a HomeBase 2 (T8010), over the station's P2P session.
+ * Download of a recording held on a HomeBase, over the station's P2P session. {@link RECORDING_STATIONS}
+ * holds every way the station models differ; the rest is shared.
  *
  * The request is `CMD_DOWNLOAD_VIDEO` (1024) in the string-pair shape
  * ({@link buildStringPairCommandPayload}) on the camera's channel. The station answers on
  * {@link RECORDING_DATA_TYPE}, tagged with that channel, with the recording's `CMD_VIDEO_FRAME` (1300) and
  * `CMD_AUDIO_FRAME` (1301) frames, faster than real time, then `CMD_DOWNLOAD_FINISH` (1304) on the control
- * data type, tagged with channel 0 whatever the camera's channel.
+ * data type, tagged with the station's {@link RecordingStation.finishChannel} whatever the camera's channel.
  *
- * Frame layouts:
+ * Frame layouts on a station that seals its recordings (HomeBase 2):
  *
  * ```
  * video, keyframe: the live E2E layout ({@link VideoFrameDecoder}), length = 179 + len exactly
@@ -18,10 +19,17 @@
  *   plaintext is a whole ADTS frame, header included
  * ```
  *
+ * Frame layouts on a station that stores them in the clear (HomeBase 3):
+ *
+ * ```
+ * video, every frame: the same 22B header, then len bytes of Annex-B H.264 or H.265, length = 22 + len
+ * audio: the same 16B header, then len bytes of ADTS AAC
+ * ```
+ *
  * @module p2p/recording-download
  */
 import { type RecordingDownload } from "../../core/contracts.js";
-import type { P2PSession } from "./p2p-session.js";
+import { type P2PSession } from "./p2p-session.js";
 /** Data type a station sends a recording's frames on: the binary channel (`0xd1 0x03`), not live video's. */
 export declare const RECORDING_DATA_TYPE = 3;
 /**
@@ -36,12 +44,56 @@ export interface RecordingFrame {
     raw: Buffer;
 }
 /**
- * The path a HomeBase 2 stores a camera's recording under: the channel as two digits, then the recording's
- * name as `yyyyMMddHHmmss` or `h265_yyyyMMddHHmmss`. Answers `undefined` for any other name, and for a channel
- * outside `0`–`99`. Both forms are digits behind one fixed prefix, so the anchored test lets no `..`, slash or
- * other character that could reach another path on the station through.
+ * How one station model stores its attached cameras' recordings and serves them over `CMD_DOWNLOAD_VIDEO`
+ * (1024): where a recording lives, whether it is sealed, which channel the finish frame is tagged with, and
+ * where a split picture continues. A model without an entry in {@link RECORDING_STATIONS} offers no download.
+ */
+export interface RecordingStation {
+    /**
+     * The path the station stores the recording named `recording` of the camera on station channel `channel`
+     * under. Answers `undefined` for a name the station could not hold. The SDK builds every path from these two
+     * values, so a request never reaches outside the camera's own folder.
+     */
+    readonly path: (channel: number, recording: string) => string | undefined;
+    /**
+     * Whether the station stores a recording sealed under its event's cipher, which opens with that cipher's ECC
+     * private key, or in the clear, which reads no key. The frame layouts of each are in this module's
+     * documentation.
+     */
+    readonly sealed: boolean;
+    /** The channel the station tags `CMD_DOWNLOAD_FINISH` (1304) with. The camera's own channel is taken too. */
+    readonly finishChannel: number;
+    /**
+     * The payload size the station fills a `CMD_VIDEO_FRAME` to when an access unit continues in the next frame
+     * ({@link AccessUnitAssembler}).
+     */
+    readonly chunkBytes: number;
+}
+/**
+ * The path a HomeBase 2 stores a camera's recording under: its {@link cameraFolder}, then the recording's name
+ * as `yyyyMMddHHmmss` or `h265_yyyyMMddHHmmss`. Answers `undefined` for any other name, and for a channel
+ * {@link cameraFolder} refuses. Both forms are digits behind one fixed prefix, so the anchored test lets no
+ * `..`, slash or other character that could reach another path on the station through.
  */
 export declare function homeBase2RecordingPath(channel: number, recording: string): string | undefined;
+/**
+ * The path a HomeBase 3 stores a camera's recording under:
+ * `/zx/emmcdata/<cameraFolder>/<yyyyMM>/<name>/<name>.zxvideo`, where the name is the recording's start as
+ * `yyyyMMddHHmmss`, whatever the codec, and `<yyyyMM>` is its first six digits. Answers `undefined` for any
+ * other name (a codec prefix, an extension or a path included), and for a channel {@link cameraFolder}
+ * refuses. The anchored test lets no character but digits through.
+ */
+export declare function homeBase3RecordingPath(channel: number, recording: string): string | undefined;
+/**
+ * The stations whose recording download is confirmed, by station model.
+ *
+ * `T8010`, HomeBase 2: `/media/mmcblk0p1/CameraNN/<name>.dat`, sealed under the event's cipher, finish tagged
+ * with channel 0, split pictures filled to {@link STATION_CHUNK_BYTES}.
+ *
+ * `T8030`, HomeBase 3: `/zx/emmcdata/CameraNN/<yyyyMM>/<name>/<name>.zxvideo`, in the clear, finish tagged
+ * with {@link STATION_CHANNEL}, a keyframe over 400000 bytes split at exactly 400000.
+ */
+export declare const RECORDING_STATIONS: ReadonlyMap<string, RecordingStation>;
 /** One recording transfer on a station session. */
 export interface RecordingTransfer {
     /** The recording's frames, in arrival order. Rejects as {@link receiveRecording} describes. */
@@ -52,7 +104,8 @@ export interface RecordingTransfer {
 /**
  * Request one recording and collect its frames until `CMD_DOWNLOAD_FINISH`. Only frames on
  * {@link RECORDING_DATA_TYPE} tagged with the camera's channel belong to it, so a live stream open on the same
- * station is never mixed in. The finish frame is taken on the camera's channel or channel 0.
+ * station is never mixed in. The finish frame is taken on the camera's channel or on `finishChannel`
+ * ({@link RecordingStation.finishChannel}).
  *
  * `frames` rejects with {@link RecordingDownloadError}: `no-data` when nothing arrives within
  * {@link FIRST_FRAME_WAIT_MS}, and `incomplete` when the transfer ends without its finish frame, on a
@@ -64,14 +117,22 @@ export declare function receiveRecording(session: P2PSession, request: {
     path: string;
     accountId: string;
     channel: number;
+    finishChannel: number;
     timeoutMs?: number;
     signal?: AbortSignal;
 }): RecordingTransfer;
 /**
- * Decode a recording's frames, in arrival order, into elementary streams. Split pictures are assembled
- * before they enter the output; an orphan continuation cannot become its own picture. Keyframes go
- * through one {@link VideoFrameDecoder}, whose media key then opens the audio; a keyframe that does not
- * open under `eccPrivateKeyHex`, and every audio frame before the first media key, are dropped. Rejects with
- * {@link RecordingDownloadError} `undecodable` when no video frame decodes.
+ * Decode a recording's frames, in arrival order, into elementary streams. `station` sets where a split
+ * picture continues ({@link RecordingStation.chunkBytes}) and whether the frames are sealed
+ * ({@link RecordingStation.sealed}). On a sealed station a keyframe goes through one {@link VideoFrameDecoder}
+ * under `eccPrivateKeyHex`, and audio opens under that decoder's current media key; a keyframe that does not
+ * open, and audio before the first media key, are dropped. On a station in the clear every video payload is read
+ * as it is, and audio is everything after its 16-byte header; a keyframe that is in fact sealed begins with an
+ * ECIES point rather than a start code, so the assembler drops it. Split pictures are assembled before they
+ * enter the output, and an orphan continuation cannot become its own picture. Audio frames whose codec byte is
+ * not AAC-LC are dropped.
+ *
+ * Rejects with {@link RecordingDownloadError} `undecodable` when no video frame decodes, and on a sealed
+ * station whose key is absent or not a P-256 key.
  */
-export declare function decodeRecording(frames: readonly RecordingFrame[], eccPrivateKeyHex: string): RecordingDownload;
+export declare function decodeRecording(frames: readonly RecordingFrame[], station: Pick<RecordingStation, "sealed" | "chunkBytes">, eccPrivateKeyHex?: string): RecordingDownload;

package/dist/transport/p2p/video.d.ts

@@ -122,23 +122,27 @@ export declare const STATION_CHUNK_BYTES = 64000;
  *
  * Two consequences worth stating. A unit that is exactly the threshold long, or an exact multiple of it,
  * ends on a full frame and is dropped as truncated — one frame in ~64000, reported, and the alternative is
- * handing a decoder bytes that may genuinely be short. And a station that fills to some OTHER size is not
- * recognised: its units stay exactly as they arrive rather than being mis-joined.
+ * handing a decoder bytes that may genuinely be short. And a station that fills to some OTHER size is
+ * recognised only by an assembler constructed with that size: elsewhere its units stay exactly as they arrive
+ * rather than being mis-joined.
  */
 export declare class AccessUnitAssembler {
     private readonly onDropped?;
+    private readonly chunkBytes;
     private open?;
     private droppedUnits;
     /**
      * @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?: ((drop: {
         carried: number;
         chunks: number;
         count: number;
-    }) => void) | undefined);
+    }) => void) | undefined, chunkBytes?: number);
     /**
      * Feed one raw `CMD_VIDEO_FRAME` payload; returns the access units it completed — none while a unit is
      * still being filled, one in the ordinary case.

package/dist/transport/rtc/command-router.d.ts

@@ -61,8 +61,8 @@ export interface RtcLiveRoute extends RtcRoute {
 export interface RtcCommandRouterDeps {
     /** The logged-in session's credentials; `undefined` while logged out. */
     identity: () => RtcIdentity | undefined;
-    /** The mega shard the account signs on (`"ie-pr"`, `"eu-pr"`, `"us-pr"`); picks the smart host. */
-    shard: () => string;
+    /** The signing shard for the route (`"ie-pr"`, `"eu-pr"`, `"us-pr"`); picks the smart host. */
+    shard: (route: RtcRoute) => string | Promise<string>;
     /** ISO country sent on the sign request (default `US`). */
     country?: string;
     logger?: Logger;
@@ -78,6 +78,8 @@ export declare class RtcCommandRouter {
     private readonly warm;
     private readonly callSources;
     private lastTransaction;
+    /** The latest shard each `call` source resolved, read by its `makeStream` (see {@link callMediaProviderFor}). */
+    private readonly callShards;
     constructor(deps: RtcCommandRouterDeps);
     dispatchCommand(route: RtcRoute, cmd: Command): Promise<void>;
     /**
@@ -132,7 +134,13 @@ export declare class RtcCommandRouter {
     trackMediaProviderFor(route: RtcRoute): MediaProvider;
     /** NVR media uses a dedicated call per camera, independent of station commands. */
     nvrMediaProviderFor(route: RtcLiveRoute, views: readonly number[]): MediaProvider;
-    /** 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.
+     */
     private callMediaProviderFor;
     /**
      * Tear down every station session (logout / shutdown). Each live source is disposed before its session
@@ -174,6 +182,14 @@ export declare class RtcCommandRouter {
      */
     private sendAwaitAck;
     private newSession;
+    /** A connected session for `sn` to reuse, or undefined (dropping a dead one). */
+    private reusable;
+    /**
+     * 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.
+     */
     private stationSession;
     /**
      * One bounded bring-up: the session is up when its command channel opens, and it fails, with the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mega-yfue/eufy-sdk",
-  "version": "0.6.0-beta.30",
+  "version": "0.6.0-beta.32",
   "description": "One typed TypeScript client for the Anker eufy v6 cloud — capability-driven devices, realtime events over P2P/MQTT/push, and live media",
   "license": "Apache-2.0",
   "author": "mega-yfue",