@mega-yfue/eufy-sdk 0.6.0-beta.3 → 0.6.0-beta.31

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

@@ -95,6 +95,12 @@ export interface P2PFrame extends P2PDataFrameHeader {
      * the values as device state without any per-capability decoder.
      */
     params?: Record<number, string>;
+    /**
+     * A station's camera-info table, one `param_type → param_value` map per channel it names (255 is the
+     * station). Set instead of {@link params} when the station answered on {@link STATION_CHANNEL}, so each
+     * channel's state can land on the device attached there.
+     */
+    channelParams?: Record<number, Record<number, string>>;
 }
 /**
  * A live PPCS session. Internal transport; a host drives cameras through the capability surface.
@@ -134,7 +140,12 @@ export declare class P2PSession extends EventEmitter {
     private audioStalled;
     private audioRetransmitTimer?;
     private lastPongData?;
-    /** When the selected peer last answered outbound P2P traffic on this connection. */
+    /**
+     * When the selected peer last answered outbound P2P traffic on this connection.
+     *
+     * Each answer also emits `peerAnswer` with this time: a PONG or an ACK from the connected address is the
+     * station replying on this connection now, which a heartbeat draws every {@link HEARTBEAT_MS}.
+     */
     private lastPeerAt?;
     /** Whether the silence has already been stated, so it is traced once per connection rather than per read. */
     private pathStaleTraced;
@@ -180,11 +191,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 +281,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 +298,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 +319,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 +351,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 +644,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 +668,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.
@@ -677,10 +748,11 @@ export declare class P2PSession extends EventEmitter {
         innerCmd?: number;
     }): void;
     /**
-     * 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.
+     * The `CMD_SET_PAYLOAD` payload of a database read or stored-image request: the JSON level-1 encrypted, or
+     * in the clear with header bytes from {@link nextClearCommandBytes} on a session that {@link sendsInTheClear}
+     * and holds no level-2 key.
      */
-    private fullTableQuery;
+    private databasePayload;
     /**
      * Request the on-device edge-AI **face roster** over P2P — the phone-free path.
      *
@@ -719,6 +791,9 @@ export declare class P2PSession extends EventEmitter {
      *
      * One read at a time per session: while one is accumulating, every {@link queryDatabase} on the
      * session throws, so a second reply cannot land in this buffer.
+     *
+     * The query's framing follows the cipher the gateway-info reply names, so on a session still negotiating
+     * its level-2 key the query waits for that to settle, up to {@link LEVEL2_SETTLE_MS} from connect.
      */
     readDatabase(table: string, opts?: {
         accountId?: string;
@@ -788,6 +863,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. */
@@ -821,6 +898,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,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,56 @@ 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 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. */
@@ -30,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
@@ -42,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/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

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