@mega-yfue/eufy-sdk 0.6.0-beta.4 → 0.6.0-beta.40

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

@@ -1,5 +1,35 @@
+/**
+ * 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 the station's {@link RecordingStation.finishChannel} whatever the camera's channel.
+ *
+ * Frame layouts on a station that seals its recordings (HomeBase 2):
+ *
+ * ```
+ * video, keyframe: the live E2E layout ({@link VideoFrameDecoder}), length = 179 + len exactly
+ * video, other frames: the same 22B header (u32@0 = len · u16@6 = frame number · u48@0x0e = stamp in ms),
+ *   then len bytes of plaintext H.264
+ * audio: 16B header (u32@0 = len · u8@5 = codec, 0 = AAC-LC), then 16B GCM tag, 12B GCM nonce and len
+ *   bytes of AES-256-GCM AAC under the media key of the preceding keyframe, AAD as live video; the
+ *   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;
 /**
@@ -14,12 +44,62 @@ export interface RecordingFrame {
     raw: Buffer;
 }
 /**
- * The path a HomeBase 2 stores a camera's recording under: the camera's channel, two digits, and the
- * recording name the event push carries. Answers `undefined` for a name that is not the station's
- * fourteen-digit `yyyyMMddHHmmss` form. The name comes from a push, so the test stays anchored and
- * digits-only: no `..`, slash or other character that could reach another path on the station gets 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 result code that opens the station's `CMD_DOWNLOAD_VIDEO` reply on the camera's channel when it holds no
+     * recording at the path, after which it sends nothing. Absent on a station whose reply is unconfirmed.
+     */
+    readonly missingCode?: 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, a missing recording
+ * answered with -111.
+ */
+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. */
@@ -30,9 +110,12 @@ 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
+ * `frames` rejects with {@link RecordingDownloadError}: `no-data` when the station's reply on the camera's
+ * channel carries `missingCode` ({@link RecordingStation.missingCode}) before any of the recording's frames, which
+ * also ends the transfer, or when nothing arrives within
  * {@link FIRST_FRAME_WAIT_MS}, and `incomplete` when the transfer ends without its finish frame, on a
  * {@link IDLE_END_MS} silence, on `timeoutMs` or on {@link MAX_TRANSFER_BYTES}. An abort rejects it at once
  * with the signal's reason. After a time bound, the byte ceiling or an abort, the transfer stops collecting
@@ -42,14 +125,27 @@ export declare function receiveRecording(session: P2PSession, request: {
     path: string;
     accountId: string;
     channel: number;
+    finishChannel: number;
+    missingCode?: 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.
+ *
+ * Frame numbers are compared only within one frame size: a keyframe whose width or height differs from the last
+ * frame that states a size is counted as the frame after the one before it, and the frames after it follow on
+ * from there. A frame whose header states no size is passed over.
+ *
+ * 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/shared-live-source.d.ts

@@ -256,7 +256,8 @@ export declare class SharedLiveSource {
      *
      * The previous stream is dropped rather than stopped through the state machine: it speaks to a session that
      * is gone, and its `stop` would be read as an upstream end. Only a warm-up that asked for a replacement
-     * rewarms, so this is inert on a source that is streaming or has already failed.
+     * rewarms, so this is inert on a source that is streaming or has already failed. Each call replaces the
+     * re-issue ticker rather than adding one, so the start goes out once per interval however often it runs.
      */
     rewarm(): void;
     /**
@@ -376,8 +377,13 @@ export declare class SharedLiveSource {
     private isKeyframe;
     /**
      * Handle a consumer leaving. When the last one detaches (1→0), release the station-session user via
-     * {@link SharedLiveSourceOptions.onIdle} (its own longer idle timer then arms) and arm the stream's
-     * linger teardown.
+     * {@link SharedLiveSourceOptions.onIdle} (its own longer idle timer then arms) and, while a stream is
+     * still running, arm its linger teardown.
+     *
+     * A source that ended its own stream ends its consumers before tearing down, and a Readable consumer
+     * detaches only once it has reached EOF — after that teardown. The source is then already `stopped`,
+     * with its session claim released, and stays so: lingering would make the owner hand it out again
+     * instead of building a source that holds a session.
      */
     private onDetach;
     /** Refcount hit zero — arm the linger teardown. A new attach in the window cancels it. */

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

@@ -73,7 +73,7 @@ export declare class VideoFrameDecoder {
 export interface AssembledAccessUnit {
     /** Unsigned 32-bit header timestamp from the first frame of this access unit. */
     sourceTimestamp: number;
-    /** True when the unit's own header flagged it a keyframe — a point a consumer may begin decoding at. */
+    /** True when header bit 0 is set, or (bit 0 clear) the payload contains an IDR — a point to begin decoding at. */
     keyframe: boolean;
     /** Frame width the unit's header declared. */
     width: number;
@@ -102,8 +102,8 @@ export declare const STATION_CHUNK_BYTES = 64000;
  * total length is nowhere on the wire and cannot be waited for. What the wire does carry, verified on two
  * models:
  *
- *  - the frames of one unit **repeat its header** — same timestamp, same {@link VideoFrameHeader.sequence} —
- *    while consecutive units differ in both;
+ *  - the frames of one unit **repeat its {@link VideoFrameHeader.sequence}**, and carry the unit's timestamp
+ *    or one stamped up to `SPLIT_UNIT_STAMP_SPREAD_MS` later;
  *  - every frame of a split unit is filled to {@link STATION_CHUNK_BYTES} except the last;
  *  - a frame that STARTS a unit begins with an Annex-B start code once decoded, and a continuation begins
  *    mid-NAL, so it does not.
@@ -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.
@@ -153,3 +157,5 @@ export declare class AccessUnitAssembler {
     /** Forget an incomplete unit, counting and reporting it. */
     discard(): void;
 }
+/** Whether a decoded payload OPENS an access unit — a continuation begins mid-NAL, with no start code. */
+export declare function beginsAccessUnit(body: Buffer): boolean;

package/dist/transport/push/store.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Persistence for FCM credentials + seen persistent-ids, so we register the FCM
+ * token ONCE and just reconnect (and don't re-receive old pushes) across runs.
+ */
+import { FileSessionStore } from "../../core/store.js";
 import type { FcmCredentials } from "./types.js";
 export interface PersistedPush {
     creds: FcmCredentials;
@@ -14,10 +19,6 @@ export declare class MemoryFcmStore implements FcmStore {
     save(p: PersistedPush): void;
     clear(): void;
 }
-export declare class FileFcmStore implements FcmStore {
-    private readonly path;
-    constructor(path: string);
-    load(): PersistedPush | null;
-    save(p: PersistedPush): void;
-    clear(): void;
+/** JSON-file FCM store: the {@link FileSessionStore} file format and write guarantees, on the push record. */
+export declare class FileFcmStore extends FileSessionStore<PersistedPush> implements FcmStore {
 }

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

@@ -14,11 +14,16 @@
  * a live pull holds it open. Sends on a session are serialised; an ACK is correlated by its outer command
  * and segment, since it carries no inner command. An ACK is not an observation of the resulting state.
  *
+ * The station's own database is read over the same channel: a `set-payload` with inner `1306`
+ * (CMD_DATABASE) answers a table and inner `1308` (CMD_DATABASE_IMAGE) a stored image, each as one
+ * notify frame carrying the whole document, zstd-compressed when large. The notify link carries
+ * unrelated station reports between them, so a reply is matched by its content, never by arrival order.
+ *
  * Live view of an attached camera rides the same session (the hub accepts one RTC session per account),
  * through one shared live source per station: the station serves one camera at a time, so a second
  * camera is refused until the first one's view ends.
  */
-import { type Command, type MediaProvider } from "../../core/contracts.js";
+import { type Command, type MediaOutputResolution, type MediaProvider } from "../../core/contracts.js";
 import type { Logger } from "../../core/logger.js";
 import { RtcSession, type RtcSessionOptions } from "./session.js";
 export interface RtcIdentity {
@@ -56,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;
@@ -72,8 +77,50 @@ export declare class RtcCommandRouter {
     private readonly lives;
     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>;
+    /**
+     * Query one on-station table over the station's control channel and answer its rows.
+     *
+     * Sends the `1350` envelope with inner `{cmd: 1306, payload: {cmd: 10000, table, payload, transaction}}`,
+     * the whole-table query, on the station channel. The hub ACKs on the command link and answers with one notify frame whose body
+     * carries `{cmd, table, data, mIntRet, msg, transaction, …}`, echoing the read's `transaction`; that echo
+     * is the only thing a reply is attributed by, and every read sends a `transaction` no other read on this
+     * router has sent. Resolves with the reply's `data` rows. Rejects with the hub's `msg` on a non-zero
+     * `mIntRet`, on an ACK refusing the envelope, at once when `signal` aborts (queued or sent), when the
+     * session closes, and when `timeoutMs` (default {@link DB_TABLE_TIMEOUT_MS}) elapses with no reply.
+     *
+     * One read or command at a time per station: the read holds the station's send queue until it settles.
+     */
+    readTable(route: RtcRoute, table: string, opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<unknown[]>;
+    /**
+     * Fetch one stored image by its on-station path over the station's control channel.
+     *
+     * Sends the `1350` envelope with inner `{cmd: 1308, payload: [{file}]}` on the station channel. The hub
+     * ACKs on the command link and answers with one notify frame whose body is `{file, content}`, `content`
+     * the image in base64, and no `transaction`; the reply is the one whose `file` equals `filePath`. A reply
+     * arriving after an abandoned read of the same path carries that path's bytes, which are the bytes a
+     * later read of it asks for. Resolves with the decoded bytes. Rejects on an ACK refusing the envelope,
+     * at once when `signal` aborts (queued or sent), when the session closes, and when `timeoutMs` (default
+     * {@link DB_TABLE_TIMEOUT_MS}) elapses with no reply.
+     *
+     * One read or command at a time per station: the read holds the station's send queue until it settles.
+     */
+    readImage(route: RtcRoute, filePath: string, opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<Buffer>;
+    /**
+     * A `transaction` stamp in the vendor app's shape, a decimal epoch-in-milliseconds string, strictly
+     * greater than the last one this router issued, so two reads in the same millisecond never share one.
+     */
+    private nextTransaction;
     /**
      * The media of a camera on a T9000: live video, a readable feed and a live still over the station's
      * session. Recording has no wire here and is refused; the optional members it has no wire for are absent.
@@ -86,8 +133,14 @@ 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. */
+    nvrMediaProviderFor(route: RtcLiveRoute, views: readonly number[], outputResolutions?: readonly MediaOutputResolution[]): MediaProvider;
+    /**
+     * 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
@@ -108,17 +161,41 @@ export declare class RtcCommandRouter {
     private refuseIfWatched;
     private newLiveSource;
     /**
-     * Completes on the command ACK or a correlated control-result notification. The notification must
-     * match the request channel, parameter and segment and contain a structured payload. Receipt does
-     * not establish physical actuation. The command is sent once, bounded by {@link ACK_TIMEOUT_MS}.
+     * Send one envelope on the station's session, queued behind its other sends, and settle as
+     * {@link sendAwaitAck} does. `body` is the inner payload; the station session, the `account_id` it is
+     * stamped with and the packet are resolved here, so a command and a read reach the wire through the same
+     * steps. With `reply.signal`, the caller's wait rejects the moment it aborts, also while the send is still
+     * queued; a send not yet made by then is skipped.
+     */
+    private sendQueued;
+    /**
+     * Without `reply`, completes on the command ACK or a correlated control-result notification. The
+     * notification must match the request channel, parameter and segment and contain a structured payload.
+     * Receipt does not establish physical actuation. Bounded by {@link ACK_TIMEOUT_MS}.
+     *
+     * With `reply`, a zero-result ACK is not the answer: the first notify body (an object) for which
+     * `reply.pick` answers a value resolves with it, one `pick` throws on rejects with that error, and every
+     * other notify frame is left alone. Bounded by `reply.timeoutMs` (default {@link DB_TABLE_TIMEOUT_MS}),
+     * and ended by `reply.signal`; one already aborted is not sent.
+     *
+     * Either way an ACK with a non-zero result code rejects, and the command is sent once.
      */
     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
      * session closed and every listener gone, when `connect()` throws, the session closes first (rejecting
-     * with the failure that closed it, when it carries one), or {@link CONNECT_TIMEOUT_MS} passes. A single
+     * with the failure that closed it, when it carries one), or {@link CONNECT_TIMEOUT_MS} passes, naming the
+     * stage the session reached and its peer's last state. A single
      * promise, so an early failure cannot leave a second one rejecting unheard.
      */
     private bringUp;

package/dist/transport/rtc/live.d.ts

@@ -6,6 +6,7 @@
  *  - Start is inner `cmd 1003` in a `1350` SET_PAYLOAD on the station channel `255`. The header byte the
  *    codec names `isResponse` carries the portal's `streamId`, `1` for a live view, and `chn_list` is an
  *    array of `{index, chn, sensor, isUps, isClicked}` objects. Stop is inner `cmd 1004`, the same way.
+ *  - The NVR start may carry `stitch_resolution: {width, height}` to set output geometry; omission keeps the NVR default.
  *  - Video arrives on the live link as portal packets `1300` on channel `100 + play id`; a single-camera
  *    view is play id `1`, whatever the camera's own channel. Each body is a fixed 22-byte media header,
  *    then the Annex B video it declares. See {@link parseMediaBody}.
@@ -17,7 +18,7 @@
  * shared live source's.
  */
 import { EventEmitter } from "node:events";
-import type { LiveStreamHandle } from "../../core/contracts.js";
+import type { LiveStreamHandle, MediaOutputResolution } from "../../core/contracts.js";
 import type { Logger } from "../../core/logger.js";
 import type { RtcSession } from "./session.js";
 import { type SegmentCounter } from "./portal-packet.js";
@@ -46,6 +47,8 @@ export interface RtcLiveOptions {
     nvr?: boolean;
     /** Optical view carried by the NVR start request; defaults to 0. */
     view?: number;
+    /** NVR live-start output geometry; absence sends no size override. */
+    outputResolution?: MediaOutputResolution;
 }
 /**
  * One camera's live pull. `start()` sends the start; a non-zero start ACK or a closed session ends it with

package/dist/transport/rtc/portal-packet.d.ts

@@ -1,14 +1,3 @@
-/**
- * The command framing a HomeBase S1 Pro (T9000) speaks over its WebRTC data channel — the wire the
- * security.eufy.com web client builds, reproduced byte-exact.
- *
- * A packet is a 16-byte header behind the ASCII magic `XZYH`, then a JSON body, sent in the clear (the
- * DTLS channel is the encryption). Replies come back with `isResponse = 1`, the same `segment` the
- * request carried, and a body whose first four bytes are a little-endian result code.
- *
- * Every offset is the portal bundle's header builder and parser (`Gr()` / `Qr()`) and its
- * `worker_sctp_send`.
- */
 export declare const PORTAL_HEADER_LENGTH = 16;
 /** The SET_PAYLOAD envelope. */
 export declare const PORTAL_CMD_SET_PAYLOAD = 1350;
@@ -61,8 +50,9 @@ export declare function isPortalPacket(buf: Buffer): boolean;
 /** A complete request packet: header + body. */
 export declare function buildPortalPacket(req: PortalRequest): Buffer;
 /**
- * Parse an inbound packet. On the command channel the body opens with the int32 result code and may
- * carry JSON after it; on the notify channel the whole body is JSON with a nested `cmd`.
+ * Parse an inbound packet, opening a zstd-compressed one first. On the command channel the body opens
+ * with the int32 result code and may carry JSON after it; on the notify channel the whole body is JSON
+ * with a nested `cmd`. `undefined` for a frame that is neither a packet nor a stream holding one.
  */
 export declare function parsePortalPacket(buf: Buffer, linkType?: number): PortalResponse | undefined;
 /** A 1..255 segment counter that never yields 0 (the portal reserves it). */

package/dist/transport/rtc/session.d.ts

@@ -15,8 +15,12 @@
  *
  * The command data channel is the session: `close` fires once, when the channel closes, the peer fails,
  * the signalling socket drops or {@link RtcSession.close} is called, even while the peer connection is
- * nominally up. A peer that cannot be built when the hub grants the relay ends the session there: the
- * failure is emitted as `error` and `close` fires carrying it.
+ * nominally up. A dropped signalling socket closes the peer with it: a hub that still sees the peer
+ * answers every later `scall` with 486 until that peer's ICE gives up. A peer that cannot be built when
+ * the hub grants the relay ends the session there: the failure is emitted as `error` and `close` fires
+ * carrying it. Before the command channel opens, a peer that fails or closes also ends the session, and so
+ * does a hub `hangup` on a `scall` session, the exchange above; {@link RtcSession.stage} names how far
+ * the bring-up got. A `call` session's pre-open hangup is not evidenced as terminal and stays logged only.
  *
  * A session whose peer is a {@link RtcPeerOptions.mediaTrack} peer has no command channel: `close` fires
  * when the peer fails or closes, and the video track's packets are emitted as `rtp`.
@@ -45,6 +49,11 @@ export interface RtcSessionEvents {
     /** One packet of the video track, in a {@link RtcPeerOptions.mediaTrack} session. */
     rtp: [packet: Buffer];
 }
+/**
+ * How far a session's bring-up got, in order: the sign fetch, the signalling socket, its auth, the placed
+ * call, the hub's relay grant, our answer to its offer, and the open command channel.
+ */
+type RtcBringUpStage = "signing" | "connecting" | "authenticating" | "calling" | "relay-granted" | "answered" | "connected";
 export declare class RtcSession extends EventEmitter<RtcSessionEvents> {
     private readonly opts;
     private readonly signaling;
@@ -58,8 +67,15 @@ export declare class RtcSession extends EventEmitter<RtcSessionEvents> {
     private closeAnnounced;
     private sdpHandled;
     private chain;
+    private stageReached;
+    private lastPeerState?;
     constructor(opts: RtcSessionOptions);
+    private get mediaTrack();
     get isConnected(): boolean;
+    /** The last bring-up stage this session reached. */
+    get stage(): RtcBringUpStage;
+    /** The peer connection's last reported state; `undefined` before it reports one. */
+    get peerState(): string | undefined;
     /**
      * Start the sequence; resolves once the call is sent. `connected` fires when the channel opens. A session
      * closed by the time the sign fetch or the auth completes rejects instead of opening the socket or
@@ -97,3 +113,4 @@ export declare class RtcSession extends EventEmitter<RtcSessionEvents> {
      */
     private onInfo;
 }
+export {};

package/dist/transport/stored-image-cache.d.ts

@@ -9,6 +9,12 @@ export declare class StoredImageCache {
     private readonly activeDevices;
     private activeDownloads;
     private generation;
+    /**
+     * Bumped by {@link clearLifecycleErrors}. A lifecycle failure from a download started under an older
+     * count is not recorded; the candidate is queued again, unless a newer one is already queued, so the
+     * current session fetches it.
+     */
+    private lifecycle;
     constructor(downloader: (url: string, deviceKey: string) => Promise<Buffer>, logger: Logger, clock?: () => number, isLifecycleError?: (error: unknown) => boolean);
     /**
      * Observe a normalized thumbnail URL and start acquisition eagerly.
@@ -20,6 +26,14 @@ export declare class StoredImageCache {
     observe(deviceKey: string, url: string): void;
     /** Return retained bytes without starting or awaiting network work. */
     snapshotStored(deviceKey: string): Promise<Buffer>;
+    /**
+     * Forget every device's recorded lifecycle failure, keeping retained bytes and candidate state.
+     *
+     * A lifecycle failure describes the session that was current when the download ran, so it no longer
+     * holds once a login succeeds again; {@link snapshotStored} then answers from the retained image, or
+     * with the reason a stored image is absent. A download in flight across the call cannot record one.
+     */
+    clearLifecycleErrors(): void;
     /** Invalidate all retained and candidate state. */
     clear(): void;
     private pump;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mega-yfue/eufy-sdk",
-  "version": "0.6.0-beta.4",
+  "version": "0.6.0-beta.40",
   "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",