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

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

@@ -62,6 +62,8 @@ export interface P2PRouterDeps {
     onClose: (stationSn: string) => void;
     onError: (err: Error) => void;
     onLevel2Ready: (stationSn: string, cipherId: number) => void;
+    /** The station answered on its own session at `atMs` — a PONG or an ACK from the connected peer. */
+    onPeerAnswer?: (stationSn: string, atMs: number) => void;
     /** A raw decoded frame — the client emits the low-level `p2p` event + runs the semantic decode. */
     onFrame: (stationSn: string, frame: P2PFrame) => void;
     /**
@@ -102,6 +104,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 +234,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;
     /**
@@ -295,24 +314,28 @@ export declare class P2PCommandRouter {
      */
     mediaProviderFor(sn: string): MediaProvider;
     /**
-     * Whether `sn` is a camera attached to a HomeBase 2 (T8010), the one station whose recording path layout
-     * and frame formats are confirmed.
+     * The {@link RecordingStation} of the station `sn` is attached to, when `sn` is a camera attached to a
+     * station with an entry in {@link RECORDING_STATIONS}. A standalone device, or a camera on any other
+     * station, answers `undefined`.
      */
-    private downloadsRecordings;
+    private recordingStationFor;
     /**
-     * Download one recording a HomeBase 2 holds for an attached camera, then decode it
-     * ({@link decodeRecording}). Downloads queue per station: the station streams one recording at a time
-     * on the camera's channel, so a download starts only once the previous one has drained
-     * ({@link RecordingTransfer.drained}), even when that one's caller already has its answer. An abort
-     * while waiting rejects without sending anything; an abort mid-transfer rejects at once and the station's
-     * turn is held until the transfer drains.
+     * Download one recording `station` holds for the attached camera `sn`, then decode it
+     * ({@link decodeRecording}). `station` is the entry {@link mediaProviderFor} bound. Downloads queue per
+     * station: the station streams one recording at a time on the camera's channel, so a download starts only
+     * once the previous one has drained ({@link RecordingTransfer.drained}), even when that one's caller already
+     * has its answer. An abort while waiting rejects without sending anything; an abort mid-transfer rejects at
+     * once and the station's turn is held until the transfer drains.
      */
     private downloadRecording;
     /** Resolve once `previous` settles, or reject as soon as `signal` aborts. */
     private waitTurn;
     /**
      * Start one recording download, once the station's previous download has drained: the decoded recording,
-     * and when the station is done sending it.
+     * and when the station is done sending it. The path is `station.path(channel, opts.recording)`, and a name
+     * it refuses rejects `invalid-recording` before anything is sent. On a sealed station the cipher's ECC key
+     * is looked up, and its absence rejects `key-unavailable` before anything is sent. A station in the clear
+     * reads no cipher, and `opts.cipherId` is not read.
      */
     private startRecordingDownload;
     /**
@@ -394,8 +417,9 @@ export declare class P2PCommandRouter {
      * {@link releaseLingeringSiblings}. A pull with consumers is never touched. The release runs before the
      * reuse branch, so a reuse frees the station as a cold start does.
      *
-     * `mayOpenOwnSession` decides whether a camera that finds the station's own session claimed may open a
-     * connection of its own for it. Only the continuous-pull egresses pass it. A still must not: it wants one
+     * `continuous` decides whether a camera that finds the station's own session claimed may open a
+     * connection of its own for it; on an {@link OWN_LIVE_SESSION_MODELS} station it always gets one, and an
+     * unwatched source left on the station's session is rebuilt there. Only the continuous-pull egresses pass it. A still must not: it wants one
      * frame, and a socket plus a level-2 negotiation per thumbnail is a cost a tile refresh cannot justify —
      * so a still asked for while a sibling is being watched contends as it always did, and the caller's
      * retained image answers it. A live view still outranks a tile; what changed is that two live views no
@@ -404,7 +428,7 @@ export declare class P2PCommandRouter {
      * The session goes into a {@link HeldSession} cell, so it can be replaced under a source that stays in
      * place.
      */
-    sharedLiveSourceFor(sn: string, opts?: SharedLiveOpts, mayOpenOwnSession?: boolean): Promise<SharedLiveSource>;
+    sharedLiveSourceFor(sn: string, opts?: SharedLiveOpts, continuous?: boolean): Promise<SharedLiveSource>;
     /**
      * Tear down any pull on this station that is lingering for ANOTHER camera, before starting this one.
      *
@@ -559,12 +583,17 @@ export declare class P2PCommandRouter {
      * yield CMAF fragments (init segment first, then a `moof`+`mdat` per keyframe boundary) muxed by the
      * dependency-free internal fMP4 muxer. The returned recording handle exposes battery-budget notices
      * and detaches its consumer on `stop`, iterator return, or iterator throw. No ffmpeg.
+     *
+     * It is a continuous pull only on an {@link OWN_LIVE_SESSION_MODELS} station; elsewhere it never opens a
+     * connection of its own.
      */
     recordFragments(sn: string, opts?: {
         fragmentSeconds?: number;
         eccPrivateKey?: Buffer;
         keepAliveMs?: number;
     } & SharedSourceHints): FragmentRecording;
+    /** Whether `stationSn` is an {@link OWN_LIVE_SESSION_MODELS} station. */
+    private ownsLiveSession;
     /**
      * **Generic P2P request/reply query.** Sends a `SET_PAYLOAD` (1350) wrapper carrying `subCmd` on the
      * device channel, then resolves with the reply frame's `payload` — the `NOTIFY_PAYLOAD` (1351)
@@ -668,6 +697,9 @@ export declare class P2PCommandRouter {
      * sources on the replaced session are discarded before closing it (see {@link tearDownStation}).
      * Replaced at most once per resolution, so a station whose replacement is silent too is returned rather
      * than closed again.
+     *
+     * `clearFallback` hands over a session whose station {@link P2PSession.refusedLevel2} instead of throwing, for
+     * a standalone device of a model in {@link CLEAR_FF09_MODELS}.
      */
     private resolveSession;
     /**
@@ -693,6 +725,9 @@ export declare class P2PCommandRouter {
      * **Station-scoped scalar** (`p2p-station-scalar` intent): the 132-byte channel-less body
      * ({@link buildDirectBinaryBody} with no `channel`) on an EXPLICIT channel, signCode 8. The
      * HomeBase's own controls ride the station broadcast channel 255 (alarm/speaker volume 1235).
+     *
+     * `form` `"auto"` seals it at the session's level, as {@link sendBySessionLevel} defines it: level-2 on a
+     * keyed session, the same body sealed level-1 on a keyless one. Absent, the send waits for the level-2 key.
      */
     private sendStationScalar;
     /** Send a level-1 int-plus-string frame with authenticated account identity injected by the transport. */

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/level2-settle.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The bound a caller waits for the level-2 negotiation to SETTLE, measured from connect.
+ *
+ * For a caller that picks its seal once from `P2PSession.hasLevel2Key` and has no second chance. A media
+ * start reads the key on every send and is re-issued by the warm-up, so it needs no wait; a property write
+ * framed level-1 to a family that only accepts level-2 is ignored, and nothing re-frames it. Session-scoped,
+ * so a station that offers no key does not charge this to every later command.
+ */
+export declare const LEVEL2_SETTLE_MS = 8000;

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?;
     /**
@@ -173,6 +180,7 @@ export declare class LiveStream extends EventEmitter {
     stop(): void;
     /** Extract the Annex-B payload from a plaintext 1300 frame (fixed 22-byte header), or undefined. */
     private plaintextAnnexB;
+    /** Emit one accepted media frame; an audio frame with no bytes past its header emits nothing. */
     private onFrame;
     /**
      * Whether this stream may take `frame` — the demultiplexer for a station that serves several cameras.
@@ -198,11 +206,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, empty for a frame that carries only 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,16 +139,16 @@ 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.
  */
  | {
     phase: "level2-unavailable";
-    reason: "no-cipher-key" | "derivation-failed" | "not-negotiating" | "session-closed" | "grace-elapsed";
+    reason: "no-cipher-key" | "derivation-failed" | "not-negotiating" | "session-closed" | "grace-elapsed" | "gateway-refused";
     cipherId?: number;
     waitedMs?: number;
 }

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. */
@@ -203,6 +224,8 @@ export declare class P2PSession extends EventEmitter {
     private readonly liveStartedChannels;
     /** The `cipher_id` this connection's `CMD_GATEWAYINFO` reply named, once its negotiation has read it. */
     private gatewayCipherId?;
+    /** Whether this connection's latest `CMD_GATEWAYINFO` reply was a refusal — see {@link gatewayInfoRefused}. */
+    private gatewayRefused;
     /** The `n` of the last `[0x01, n]` header this connection sent in the clear — see {@link nextClearCommandBytes}. */
     private clearCommandCount;
     private readonly unackedLiveStarts;
@@ -260,7 +283,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 +300,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 +321,15 @@ 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. A {@link gatewayInfoRefused} reply names no cipher, so it settles at once
+     * with no cloud lookup, and a later reply naming a cipher withdraws the refusal.
      */
     private negotiateLevel2Key;
     /**
@@ -327,7 +354,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
@@ -494,6 +529,11 @@ export declare class P2PSession extends EventEmitter {
     sendIntStringCommand(commandType: number, value: number, valueSub: number, strValue: string, channel?: number): void;
     /** Send a level-1 {@link buildStringPairCommandPayload} command on `channel`. */
     sendStringPairCommand(commandType: number, strValue: string, strValueSub: string, channel: number): void;
+    /**
+     * Whether this connection's station answered `CMD_GATEWAYINFO` with a refusal ({@link gatewayInfoRefused}) and
+     * no key that frames a set-payload is held.
+     */
+    get refusedLevel2(): boolean;
     /**
      * Send a **level-2 (AES-256-GCM, signCode 8) control payload** to a HomeBase-attached device. The
      * target camera is selected by `channel` (= device_channel) + the `mChannel` envelope — the same
@@ -504,8 +544,12 @@ export declare class P2PSession extends EventEmitter {
      * On a session holding only the AES-128-ECB level-2 key of an RSA cipher, the frame is the level-1
      * layout ({@link sendRawLevel1Bytes}) sealed under that key at encryption type 2: the encryption-type
      * byte names the key the body is sealed with (1 = level-1 key, 2 = the negotiated key).
+     *
+     * With `clearOnRefusal` on a session that {@link refusedLevel2}, the frame goes in the clear in the vendor
+     * app's form for such a device: header bytes `[01 00]`, signCode 0, and a body of `{cmd, payload}` alone.
+     * Without it, a refused session answers `false` and sends nothing.
      */
-    sendControlLevel2(cmd: number, channel: number, accountId: string, payload: Record<string, unknown>, mValue3?: number): boolean;
+    sendControlLevel2(cmd: number, channel: number, accountId: string, payload: Record<string, unknown>, mValue3?: number, clearOnRefusal?: boolean): boolean;
     /**
      * Send a **level-2 (GCM, signCode 8) frame whose plaintext is exactly `json`** — no
      * `{account_id,cmd,mChannel,…}` envelope. The target device is selected by the frame-header
@@ -612,6 +656,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 +680,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 +760,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 +803,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 +875,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 +910,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;