@mega-yfue/eufy-sdk 0.6.0-beta.14 → 0.6.0-beta.16

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

@@ -1,6 +1,7 @@
 import { type SessionEntry } from "../../core/crypto.js";
 import { type SessionStore } from "../../core/store.js";
 import { type Logger } from "../../core/logger.js";
+import type { EufyDevice } from "../../core/types.js";
 import type { SecureMqttCredentials } from "../mqtt/secure-mqtt.js";
 export type RegionShard = "eu-pr" | "us-pr";
 /**
@@ -354,11 +355,11 @@ export declare class MegaHttpClient {
     /** Authed call to a mega service host: app-{service}-{region}.eufy.com. */
     post<T = unknown>(service: string, path: string, body?: unknown, headerOverrides?: Record<string, string>): Promise<T>;
     /**
-     * Fetch the per-station DSK key used in the P2P cloud-lookup payload. Mirrors
+     * Fetch the per-station DSK key using each station's reported cloud category. Mirrors
      * the legacy `get_dsk_keys` body shape on the mega devicerelation service.
      * The P2P *local* lookup path does not need this; only the cloud path does.
      */
-    getDskKeys(stationSns: string[], priorDsks?: Record<string, string>): Promise<Record<string, {
+    getDskKeys(stations: ReadonlyArray<Pick<EufyDevice, "sn" | "category">>, priorDsks?: Record<string, string>): Promise<Record<string, {
         dskKey: string;
         expiration: number;
     }>>;

package/dist/transport/p2p/audio-frame.d.ts

@@ -12,3 +12,16 @@ export declare const AUDIO_TYPE_OFFSET = 5;
  * itself when a stream produces no audio at all, to feed its decoder silence.
  */
 export declare const AUDIO_CODECS: Readonly<Record<number, AudioCodec>>;
+/**
+ * Whether an audio frame is sealed: after its header, a 16-byte GCM tag and a 12-byte nonce precede the
+ * `u32@0` bytes its header declares, where a frame in the clear carries those bytes straight after the header.
+ * A stream whose keyframes wrap their media key in an ECIES envelope seals its audio this way, measured on
+ * HomeBase recordings and on HomeBase 3 live streams answering a P-256 start.
+ */
+export declare function isSealedAudio(frame: Buffer): boolean;
+/**
+ * The payload of a sealed audio frame ({@link isSealedAudio}), opened with AES-256-GCM under `mediaKey`, the
+ * media key of the keyframe before it, with the video frames' AAD. Answers `undefined` for a frame that is not
+ * sealed or does not authenticate under that key.
+ */
+export declare function openSealedAudio(frame: Buffer, mediaKey: Buffer): Buffer | undefined;

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

@@ -224,8 +224,8 @@ export declare function buildRawCommandPayload(data: Buffer, channel?: number, s
 export declare function buildAckPayload(dataTypeHeader: Buffer, seqNo: number): Buffer;
 /** Parse the 16-byte data-frame header that follows the "XZYH" magic. */
 export declare function parseDataFrameHeader(frame: Buffer): P2PDataFrameHeader;
-/** Parse a LOOKUP_ADDR or RLY_TO message's leading address record. */
-export declare function parseLookupAddr(msg: Buffer): Address;
+/** A LOOKUP_ADDR message's leading address record, or `undefined` for a message too short to carry it. */
+export declare function parseLookupAddr(msg: Buffer): Address | undefined;
 /** The relay servers a LIST_REQ_ACK names, in the order listed, without the unspecified address; records past the message's end are dropped. */
 export declare function parseRelayList(msg: Buffer): Address[];
 /** A RLY_PORT_ACK's mark and relay port, or `undefined` for a message too short to carry them. */

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

@@ -102,6 +102,18 @@ export declare class P2PCommandRouter {
      * {@link liveSources} is a claim in flight.
      */
     private readonly liveSessionKeys;
+    /**
+     * The live source build in flight per `${parentSn}:${channel}`, settled once its connection is opened
+     * or refused.
+     *
+     * A build awaits its media session before it can file the source in {@link liveSources}, so a second
+     * request for the same camera in that window finds nothing cached. Building a second source there
+     * overwrites the first, and the orphan's teardown then closes the connection the cached one streams
+     * on. A request that finds a build here waits for it, until its own signal aborts, then resolves its
+     * session again and reuses what the build filed, or builds its own when that build failed. The entry
+     * is removed when the build settles and its promise never rejects, so each wait ends on a later state.
+     */
+    private readonly liveSourceBuilds;
     /**
      * The open talkback per `${parentSn}:${channel}`, if any. The device plays one audio stream at a
      * time and the session carries one audio sequence, so this path is exclusive where a live pull is
@@ -220,6 +232,11 @@ export declare class P2PCommandRouter {
      * so a start issued before the key arrives is dropped as `media-command-unsent`, and the stream then
      * shows nothing until a later keepalive tick happens to find the key. A connected session that cannot
      * carry the start is not a connected session, so this refuses rather than returning one.
+     *
+     * A session refused its key within the grace, or never connected, is closed and dropped from the manager at
+     * once. Nothing else releases it: no source holds it, a wired station's session never idles out, and the
+     * manager hands the same session to every later open of the camera, so the next open dials a fresh
+     * connection instead. A session another open has since replaced is left to its own close.
      */
     private openMediaSession;
     /**

package/dist/transport/p2p/database-wire.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Database wire — the ids and the whole-table query a station's on-station table and stored-image
+ * reads are built from.
+ *
+ * A HomeBase answers them over its P2P session and a T9000 over its portal control channel, with the
+ * same inner payloads, so both transports build their reads from this one module. The barrel does not
+ * re-export it: these are wire ids, not part of the package surface.
+ *
+ * @module p2p/database-wire
+ */
+/** CMD_DATABASE_IMAGE (1308) — fetch one stored image by its on-station path. */
+export declare const CMD_DATABASE_IMAGE = 1308;
+/** CMD_DATABASE (1306) — query one on-station table; reply carries `{cmd:10000,count,data:[…]}`. */
+export declare const CMD_DATABASE = 1306;
+/**
+ * Inner query cmds carried in a {@link CMD_DATABASE} payload. `FULL_TABLE` reads one table whole;
+ * `COMBINATION_WITH_AI` is the AI event-history read that bundles the face roster.
+ */
+export declare const DB_QUERY: {
+    readonly FULL_TABLE: 10000;
+    readonly COMBINATION_WITH_AI: 10011;
+    readonly QUERY_LOCAL: 10017;
+};
+/** How long a station's database reply has to arrive whole, when the caller states no bound. */
+export declare const DB_TABLE_TIMEOUT_MS = 15000;
+/**
+ * The query params the vendor app sends with a whole-table `CMD_DATABASE` read (inner `cmd 10000`).
+ * `count` bounds the row count.
+ */
+export declare function fullTableQuery(count?: number): Record<string, unknown>;

package/dist/transport/p2p/live-stream.d.ts

@@ -7,9 +7,11 @@
  *  - **Plaintext** (`signCode 0`, e.g. HomeBase-attached cameras): a fixed 22-byte frame header
  *    (`parseVideoFrameHeader`) followed directly by Annex-B NAL units — verified live (960×540,
  *    keyframe = header flag bit0). We strip the 22-byte header.
- *  - **Encrypted** (E2E cameras): the body is AES-256-GCM under a per-stream media key wrapped in a
- *    keyframe ECIES envelope. If an `eccPrivateKey` is supplied we run `VideoFrameDecoder`; otherwise
- *    those frames are skipped (no key → no video).
+ *  - **Encrypted keyframes**: either the AES-256-GCM body under a media key wrapped in an ECIES envelope
+ *    for an offered P-256 key ({@link VideoFrameDecoder}), or an AES-ECB head under a media key wrapped for
+ *    the session's RSA key ({@link P2PSession.decodeVideoFrame}). An attached camera's start on a station
+ *    with a {@link P2PSession.mediaEccPrivateKey} offers that P-256 key first, so its stream decodes with
+ *    that pair unless `eccPrivateKey` names another.
  *
  * Emits: `video` ({@link LiveVideoFrame} — Annex-B), `audio` ({@link LiveAudioFrame}), `start`, `stop`,
  * `error`.
@@ -54,7 +56,10 @@ export interface LiveStreamOptions {
      * however long the station keeps serving that sibling instead of this one.
      */
     channel?: number;
-    /** Camera ECC private key (32B) for E2E/encrypted cameras; omit for plaintext cameras. */
+    /**
+     * P-256 private key (32B) whose public point the camera wraps each keyframe's media key for. Defaults, on an
+     * attached camera, to the session's `P2PSession.mediaEccPrivateKey`, the pair its start offers.
+     */
     eccPrivateKey?: Buffer;
     /** Admin account id — required for the level-2 (`signCode 8`) media-start payload selecting a camera. */
     accountId?: string;
@@ -112,6 +117,8 @@ export declare class LiveStream extends EventEmitter {
     private tracedFirstVideoUnit;
     private tracedFirstKeyframe;
     private tracedDecodeFailures;
+    /** How the frame that opened the latest access unit was read; see {@link settleStartKey}. */
+    private unitOpenedBy;
     private tracedFirstForeignFrame;
     private stallTimer?;
     /**
@@ -198,11 +205,30 @@ export declare class LiveStream extends EventEmitter {
      */
     private acceptsMedia;
     /**
-     * The Annex-B payload of a frame that starts an access unit. The session decodes it when it can (it
-     * holds the RSA private key, and handles the plaintext form); the legacy header-strip and the ECIES
-     * {@link VideoFrameDecoder} are the fallbacks for an E2E camera.
+     * The Annex-B payload of a frame that starts an access unit. The authenticated ECIES/GCM
+     * {@link VideoFrameDecoder} goes first: its HMAC and GCM checks fail closed on a frame not sealed for its
+     * key. The session's RSA path cannot: on Node ≥ 24.5, PKCS#1 v1.5 decryption of a key not wrapped for it
+     * returns pseudo-random bytes instead of throwing (implicit rejection), which would decode an ECC
+     * keyframe into noise. The session's decode, which also passes plaintext frames, and the header strip
+     * follow. A payload that opens an access unit records how it was read: by the ECIES path, or otherwise by
+     * its sign code, sealed (`"rsa"`) or in the clear (`"plain"`).
      */
     private annexbOf;
+    /**
+     * Tell the session how this keyframe was opened, which answers the attached starts on this channel
+     * ({@link P2PSession.settleAttachedKey}), and re-issue the start when the session asks for one: a plaintext
+     * keyframe answering the session's P-256 offer, from a camera that did not use the point, which the next
+     * start asks with RSA. Only a delivered keyframe answers: a frame no key opens, or a continuation without the
+     * frame that opened its unit, delivers nothing.
+     */
+    private settleStartKey;
+    /**
+     * The payload of an audio frame. On a stream with an ECIES decoder, a sealed frame ({@link isSealedAudio}) is
+     * opened under the media key of the latest keyframe, and answers `undefined` when it does not open or arrives
+     * before any keyframe gave a media key, since its bytes are ciphertext. Every other frame is the bytes after
+     * its header.
+     */
+    private audioPayload;
     /**
      * Report an access unit the transport could not complete.
      *

package/dist/transport/p2p/live-trace.d.ts

@@ -23,6 +23,8 @@ export type LiveTrace =
     topology: "attached" | "own";
     action: "start" | "keepalive";
     level2: boolean;
+    /** The media-key type an attached start offered. */
+    key?: "ecc" | "rsa";
 }
 /** The device acknowledged a retained start, or that start was repeated / abandoned unacknowledged. */
  | {
@@ -137,10 +139,10 @@ export type LiveTrace =
  *
  * Every ending of a level-2 wait carries one of these reasons, so a start refused for want of a key is
  * accounted for however it ended. `grace-elapsed` is a wait that ran out and states how long was waited;
- * the rest are answered without waiting, because the negotiation is one-shot per connection and a
- * concluded one is final. `no-cipher-key` and `derivation-failed` are about this account's cipher
- * material, `not-negotiating` and `session-closed` about the station or its connection — and only a
- * reason reached under a negotiation has a cipher to name.
+ * the rest are answered without waiting, because a concluded negotiation stays concluded until a
+ * re-prompt for `CMD_GATEWAYINFO` re-opens it. `no-cipher-key` and `derivation-failed` are about this
+ * account's cipher material, `not-negotiating` and `session-closed` about the station or its connection —
+ * and only a reason reached under a negotiation has a cipher to name.
  *
  * A `grace-elapsed` start proceeds at level 1 where it has such a form, and not at all where it does not.
  */

package/dist/transport/p2p/p2p-session.d.ts

@@ -180,11 +180,21 @@ export declare class P2PSession extends EventEmitter {
     private level2Seq;
     private rsaPrivateKey?;
     private rsaModulusHex?;
-    /** Guards the one-shot level-2 key negotiation kicked off by the GATEWAYINFO reply. */
+    /** The P-256 pair an attached camera's media start offers; see {@link mediaEccPrivateKey}. */
+    private mediaEcc?;
+    /**
+     * Per attached channel, the media-key type its latest start offered on this connection, or that last answered,
+     * and whether a keyframe has answered it. See {@link attachedStartKey} and {@link settleAttachedKey}.
+     */
+    private readonly attachedStartKeys;
+    /**
+     * Whether a level-2 key negotiation kicked off by a GATEWAYINFO reply is in flight. Cleared when it
+     * settles, so a later reply — the answer to {@link repromptLevel2Key} — negotiates again.
+     */
     private level2Negotiating;
     /**
      * Whether waiting for a level-2 key can still change the answer: `false` once one has been negotiated,
-     * once the one-shot negotiation concluded without one, and from the start when nothing can negotiate one.
+     * once a negotiation concluded without one, and from the start when nothing can negotiate one.
      */
     private level2Pending;
     /** Waiters parked in {@link awaitLevel2Key}, woken the moment the negotiation settles either way. */
@@ -260,7 +270,8 @@ export declare class P2PSession extends EventEmitter {
      * The session grace runs from connect, when the station is prompted for `CMD_GATEWAYINFO`. A negotiation
      * beginning later does not restart it: best-effort media can proceed without the key, and restarting
      * would charge another grace to a source that may already be streaming. A session whose negotiation has
-     * settled answers without waiting at all, since being one-shot is what makes that answer final.
+     * settled answers without waiting at all: the answer stands until {@link repromptLevel2Key} re-opens the
+     * wait, since the station is prompted for `CMD_GATEWAYINFO` only on connect and on that re-prompt.
      *
      * An own-session camera whose grace expires here is NOT thereby a camera that will fail to stream. Measured
      * on one account: own-session cameras of two device types negotiated a key, three others never did, and
@@ -276,12 +287,13 @@ export declare class P2PSession extends EventEmitter {
     /**
      * Ask the station for its gateway info a second time, re-opening a negotiation that concluded without a key.
      *
-     * The negotiation is one-shot per connection: the station is prompted once on connect, and a reply that
-     * never lands settles the wait so {@link awaitLevel2Key} answers `false` at once forever after. That is the
+     * Without this the station is prompted once on connect, and a negotiation that settles without a key
+     * leaves {@link awaitLevel2Key} answering `false` at once for the rest of that connection. That is the
      * right answer for best-effort media, which proceeds at level-1 — but an operation whose ONLY wire is
      * level-2 is then refused for the whole life of that connection, while a fresh session over the same
      * device negotiates a key normally. Measured: a session that had settled refused every such operation
-     * until it was rebuilt, at which point the station answered with a cipher id straight away.
+     * until it was rebuilt, at which point the station answered with a cipher id straight away. The reply to
+     * this ask runs the negotiation again and settles the re-opened wait either way.
      *
      * Bounded to one extra ask per connection, so a burst of such operations cannot turn a silent station into a
      * flood, and answers whether it asked — `false` when a key is already held, when nothing can negotiate one,
@@ -296,13 +308,14 @@ export declare class P2PSession extends EventEmitter {
      * `cipher_id`, resolve that cipher's private keys once (cloud `get_ciphers`, via the configured
      * `resolveCipherKey`), run the ECIES unwrap with the ECC key, and `setLevel2Key()`. A cipher with no
      * ECC key uses its RSA key instead and holds the RSA-decrypted 16-byte key as the AES-128-ECB level-2
-     * key. One-shot; emits `level2Ready` only when the AES-256-GCM key is negotiated, traces
+     * key. Emits `level2Ready` only when the AES-256-GCM key is negotiated, traces
      * `level2-set-payload-only` instead for the AES-128-ECB key, and emits `error` when the ECC unwrap
      * fails; an RSA unwrap failure is only traced (non-fatal either way — level-1 traffic keeps working).
      *
-     * Every outcome settles the wait in {@link awaitLevel2Key}, because being one-shot is what makes a
-     * failure final for this connection generation: nothing will retry it there, so a later command must be
-     * told at once rather than left to time out against a key that is not coming.
+     * Every outcome settles the wait in {@link awaitLevel2Key}, so a later command is told at once rather than
+     * left to time out against a key that is not coming. Settling also re-opens the negotiation, so a later
+     * GATEWAYINFO reply in the same connection generation runs it again; a lookup that completes after its
+     * generation ended settles nothing.
      */
     private negotiateLevel2Key;
     /**
@@ -327,7 +340,15 @@ export declare class P2PSession extends EventEmitter {
      * inside the bind callback, where a refusal is thrown out of reach of this session and ends the process.
      */
     private requestReceiveBuffer;
-    /** Open the socket and start the lookup → hole-punch handshake. */
+    /**
+     * Open the socket and start the lookup → hole-punch handshake.
+     *
+     * A socket closed or failing while binding never invokes its bind callback, so the bind wait also
+     * settles on the socket's `close` and `error`. On `close`, a connect whose session was closed meanwhile
+     * returns without starting the handshake, so it never sends a lookup or arms a timer on a closed
+     * session. On `error`, connect closes the session and rejects with {@link StationUnreachableError}
+     * carrying the bind error as its `cause`.
+     */
     connect(): Promise<void>;
     /** Cached across every `P2PSession` in this process — the local outbound IPv4 doesn't vary by
      * station, so there's no reason to re-probe it per session (e.g. once per station in a fleet). Only
@@ -612,6 +633,10 @@ export declare class P2PSession extends EventEmitter {
      * Send a CMD_SET_PAYLOAD(1350) wrapping `{account_id, cmd:<subCmd>, mChannel, mValue3:<subCmd>,
      * payload}`, encrypted level-2 (AES-256-GCM, signCode 8) — the app's media-control path. The
      * camera is selected by `mChannel` (= the device's `device_channel`) AND the frame-header channel.
+     * A start (HomeBase-controlled camera path, the V6 app's media-start envelope) also carries an
+     * `accountId` inside its payload and the media key `key` offers (see {@link attachedStartKey}). A start
+     * offering the P-256 point labels itself `ClientOS: "IOS"`, as every simple attached start in the app
+     * captures that carry that key form does; the RSA start keeps `"Android"`.
      */
     private sendMediaPayloadLevel2;
     /**
@@ -632,6 +657,41 @@ export declare class P2PSession extends EventEmitter {
      * (T8171 2560×1440, T8210 640×480). Returns `undefined` on failure (frame is skipped).
      */
     private rsaUnwrapKey;
+    /**
+     * The media-key type the next attached start sent on `channel` offers, recorded as offered: ECC, the current
+     * app's form, for the first start this connection sends there; RSA for every start after one that no keyframe
+     * answered before it was re-issued; and, once a keyframe has answered, the type that opened it, until
+     * {@link settleAttachedKey} records another. Only an opened keyframe answers: frames no key opens, and deltas,
+     * do not. A re-issue is a full restart on an attached camera, so a camera that cannot read the point is asked
+     * with RSA, the start every station answers, and is not asked with the point again while that goes unanswered.
+     * A stream decoding with the session's pair reads either answer. A station without {@link mediaEccPrivateKey}
+     * is offered RSA only. A start that cannot be sent offers nothing and records nothing.
+     */
+    private attachedStartKey;
+    /**
+     * Record how a keyframe of `channel` was opened, which answers the starts there. A keyframe opened under a
+     * key type is an answer of that type, whichever type the latest start offered: a station can serve the
+     * P-256 start after the RSA re-issue went out. A plaintext keyframe
+     * answering an unanswered P-256 offer is a camera that did not use the point, and the next start there offers
+     * RSA; once a P-256 answer has been opened it changes nothing, and answering RSA, it settles RSA. Answers
+     * whether a new start is needed. A channel no attached start has offered a key on is left as it is.
+     */
+    settleAttachedKey(channel: number, opened: "ecc" | "rsa" | "plain"): boolean;
+    /**
+     * The 32-byte P-256 private scalar paired with the point an attached camera's media start offers as `key`.
+     * A camera answering that start wraps each keyframe's AES-256-GCM media key in an ECIES envelope for this
+     * key ({@link VideoFrameDecoder}). Generated once per session, like the RSA pair.
+     *
+     * `undefined` unless the station is a HomeBase 3 (`T8030`): the app's P-256 start and the device runs
+     * that answered it were both observed on that station only.
+     */
+    get mediaEccPrivateKey(): Buffer | undefined;
+    /**
+     * The session's P-256 pair: the private scalar as 32 bytes, and the public point as 128 hex characters,
+     * `x ‖ y` without the uncompressed-point prefix, the form the current app's attached-camera start carries in
+     * `key`. `ECDH.getPrivateKey()` drops a scalar's leading zero bytes, so the scalar is padded back to 32.
+     */
+    private mediaEccPair;
     /**
      * The RSA-1024 public-key modulus (128-byte hex) the station uses to wrap the per-stream media
      * key. Lazily generates a keypair; `rsaPrivateKey` decrypts the media key the station returns.
@@ -682,11 +742,6 @@ export declare class P2PSession extends EventEmitter {
      * and holds no level-2 key.
      */
     private databasePayload;
-    /**
-     * Standard "give me the whole table" query params the eufy app uses for a direct
-     * `CMD_DATABASE` read (inner `cmd 10000`). `count` bounds the row count.
-     */
-    private fullTableQuery;
     /**
      * Request the on-device edge-AI **face roster** over P2P — the phone-free path.
      *
@@ -797,6 +852,8 @@ export declare class P2PSession extends EventEmitter {
      *
      * Only once the data type's reorder wait passes, or {@link REORDER_MAX_DATAGRAMS} pile up, is the datagram
      * treated as lost: a pending frame is discarded and delivery resumes from the earliest held datagram.
+     *
+     * A datagram shorter than the 8-byte DATA header carries no sequence number and is dropped unacknowledged.
      */
     private onData;
     /** Hold a datagram that arrived past a hole, and arm the wait for the missing one to be repeated. */
@@ -830,6 +887,13 @@ export declare class P2PSession extends EventEmitter {
      */
     private resetInboundSequencing;
     private ackTypeHeader;
+    /**
+     * Decrypt and dispatch one inbound data frame.
+     *
+     * A `CMD_GATEWAYINFO` (1100) reply carries the ECIES envelope for the level-2 session key. When a
+     * cipher-key resolver is configured, no key that seals a set-payload is held and no negotiation is in
+     * flight, the reply starts one (async, fire-and-forget); a reply landing while one is in flight is ignored.
+     */
     private handleFrame;
     private send;
     /** Finish the END send on the current socket before closing it; send completion is not a peer ACK. */

package/dist/transport/p2p/readable-egress.d.ts

@@ -25,6 +25,8 @@ export interface ReadableEgressOptions {
 /**
  * Wrap a shared-source {@link Consumer} in a fresh Readable. The consumer is detached when the
  * Readable is destroyed/ended, so callers own the lifetime by owning the stream.
- * Frames arrive through onMedia, preserving their source-arrival metadata.
+ * Frames arrive through onMedia, preserving their source-arrival metadata. The consumer's battery
+ * `budget` notice is re-emitted unchanged as a `budget` event carrying a {@link StreamBudgetNotice};
+ * without an `extend()` within its grace the shared source ends the consumer and the Readable reaches EOF.
  */
 export declare function openReadableFromConsumer(consumer: Consumer, opts?: ReadableEgressOptions): Readable;

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

@@ -1,3 +1,25 @@
+/**
+ * Download of a recording held on a HomeBase 2 (T8010), over the station's P2P session.
+ *
+ * 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.
+ *
+ * Frame layouts:
+ *
+ * ```
+ * 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
+ * ```
+ *
+ * @module p2p/recording-download
+ */
 import { type RecordingDownload } from "../../core/contracts.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. */

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;
     /**

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

@@ -153,3 +153,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,6 +14,11 @@
  * 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.
@@ -72,8 +77,48 @@ export declare class RtcCommandRouter {
     private readonly lives;
     private readonly warm;
     private readonly callSources;
+    private lastTransaction;
     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.
@@ -108,9 +153,24 @@ 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;

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,10 @@
  *
  * 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.
  *
  * 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`.

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;