@mega-yfue/eufy-sdk 0.4.0-beta.2 → 0.4.0-beta.20

package/dist/model/capabilities/camera.d.ts

@@ -552,6 +552,7 @@ export declare const CAMERA_MEMBERS: {
     } | undefined) => Promise<Buffer<ArrayBufferLike>>>;
     readonly openReadable: import("./members.js").ProvidedMember<"media", ((opts?: Parameters<NonNullable<MediaProvider["openReadable"]>>[0]) => Promise<import("node:stream").Readable>) | undefined>;
     readonly recordFragments: import("./members.js").ProvidedMember<"media", ((opts?: Parameters<NonNullable<MediaProvider["recordFragments"]>>[0]) => import("../../core/contracts.js").FragmentRecordingHandle) | undefined>;
+    readonly downloadRecording: import("./members.js").ProvidedMember<"media", ((opts: Parameters<NonNullable<MediaProvider["downloadRecording"]>>[0]) => Promise<import("../../core/contracts.js").RecordingDownload>) | undefined>;
     /**
      * Push audio from the host to this camera's speaker. Gated on the **speaker** param specifically —
      * not the `audio` capability, which resolves on a microphone alone and would advertise a speaker the

package/dist/model/capabilities/doorbell.d.ts

@@ -164,7 +164,7 @@ export declare function parseQuickResponses(voiceList: Array<{
 }>): QuickResponse[];
 /**
  * `doorbell` — chime / ringtone configuration. CONFIRMED against a real Video Doorbell (T8214):
- * the live ids are the `1702-1719` `CMD_BAT_DOORBELL_*` range (provenance "mega", observed). The
+ * the live ids are the `1702-1719` `CMD_BAT_DOORBELL_*` range, observed on that device. The
  * legacy `2015/2022/1306` ids are excluded — they appear on NO owned device. The button-
  * press *event* (ring) is delivered out-of-band via `CMD_DOORBELL_NOTIFY_PAYLOAD` (1701) /
  * push/MQTT — it is handled by the Phase-1 event normalizers, not as a device-list param.
@@ -185,9 +185,9 @@ export declare function parseQuickResponses(voiceList: Array<{
 export declare const DOORBELL_MEMBERS: {
     /**
      * The HOMEBASE as the doorbell's chime — the hub plays the ring, not the wired chime box
-     * `mechanicalChimeSwitch` drives. `provenance` is "verified" on our own decrypt of the app's frame,
-     * not merely the param id observed live: direct-binary `[ch][value][acct]`, 1=on/0=off, the same shape
-     * as its 1703 sibling — captured, not inferred from the shared param range.
+     * `mechanicalChimeSwitch` drives. `provenance` is "verified" on our own decrypt of the app's frame:
+     * direct-binary `[ch][value][acct]`, 1=on/0=off, the same shape as its 1703 sibling — captured, not
+     * inferred from the shared param range.
      */
     readonly chimeSwitch: {
         readonly param: 1702;
@@ -198,9 +198,8 @@ export declare const DOORBELL_MEMBERS: {
         readonly write: (v: string | number | boolean, ctx: import("./types.js").CommandContext) => import("../../core/contracts.js").Command;
     };
     /**
-     * `provenance` is "verified" not "mega": the actual write wire is confirmed (
-     * our own P2P decrypt), not merely the param id observed on a live device. Direct-binary
-     * `[ch][value][acct]`, 1=on/0=off — verified live on a T8214 (ON then OFF).
+     * `provenance` is "verified" on our own P2P decrypt of the write wire: direct-binary
+     * `[ch][value][acct]`, 1=on/0=off, verified live on a T8214 (ON then OFF).
      */
     readonly mechanicalChimeSwitch: {
         readonly param: 1703;
@@ -231,7 +230,7 @@ export declare const DOORBELL_MEMBERS: {
         readonly type: "number";
         readonly unit: "%";
         readonly kind: "percent";
-        readonly provenance: "mega";
+        readonly provenance: "verified";
         readonly writtenElsewhere: true;
         readonly description: string;
     };
@@ -325,7 +324,7 @@ export declare const DOORBELL_MEMBERS: {
         readonly param: 1710;
         readonly type: "string";
         readonly kind: "text";
-        readonly provenance: "mega";
+        readonly provenance: "verified";
         readonly description: string;
     };
     /**

package/dist/model/capabilities/manifest.d.ts

@@ -61,8 +61,14 @@ export interface ActionDescriptor extends ActionSpec {
 /** What one capability exposes on a device — the join of its bound object and its own declaration. */
 export interface CapabilityDescriptor {
     capability: Capability;
-    /** The fluent accessor this capability is reached under: `dev[accessor]()`. */
-    accessor: string;
+    /**
+     * The fluent accessor this capability is reached under: `dev[accessor]()`.
+     *
+     * Absent for a capability with nothing to bind — one whose whole surface is inbound events, so it
+     * declares no members and no `actions()` and therefore has no object to reach. Such a capability is
+     * described for its {@link events} alone; every other field is empty.
+     */
+    accessor?: string;
     /** The reads INSTALLED on this device, never the theoretical set. */
     reads: readonly ReadDescriptor[];
     /** The installed actions that carry a description. */
@@ -102,6 +108,16 @@ export interface DeviceManifest {
  * Parameterised over the module list; the barrel binds it to the real one. A capability the device did
  * not bind — because it does not have it, or because nothing is bound yet — contributes no descriptor
  * at all.
+ *
+ * With ONE exception, and it is not a bound object: a capability whose whole surface is inbound events
+ * declares no members and no `actions()`, so `buildActions` builds nothing for it and there is no
+ * object here to walk. Its events are still device truth, and the resolved set in {@link
+ * AvailabilityContext.capabilities} is what says this device has it — so it is described from its own
+ * declaration, with no {@link CapabilityDescriptor.accessor} and every other field empty, and only on
+ * a device with at least one bound object.
+ *
+ * Claims resolve against an empty read set there, which is the truthful evidence — a module that binds
+ * nothing installs no getter, so a `reads` claim cannot hold. A topology claim still applies.
  * @internal
  */
 export declare function describeBound(modules: readonly CapabilityModule[], bound: Readonly<Record<string, unknown>>, ctx?: AvailabilityContext): CapabilityDescriptor[];

package/dist/model/capabilities/motion.d.ts

@@ -98,7 +98,6 @@ export declare const MOTION_CMD: {
      * payload key AND pass mChannel 0 explicitly; the two are separate choices, not linked.)
      *
      * ⚠️ Replay + readback confirmed on a HomeBase-attached T8425 (1719 `0`→`1`→`0`), NOT byte-captured.
-     * Provenance is `apk`, not `verified`: a divergent-but-also-accepted frame can't be ruled out.
      */
     readonly HUMAN_ONLY_AT_NIGHT: 1719;
     /**
@@ -112,7 +111,7 @@ export declare const MOTION_CMD: {
      * form, so a feature that is on reads as off.
      * Decoded by {@link decodeRadarWdSwitch} to match the app.
      *
-     * ⚠️ Replay + readback confirmed on a T8214 (2706 `0`→`1`→`0`), NOT byte-captured. Provenance `apk`.
+     * ⚠️ Replay + readback confirmed on a T8214 (2706 `0`→`1`→`0`), NOT byte-captured.
      */
     readonly LOITERING_DETECTION: 2706;
     /**
@@ -354,7 +353,7 @@ export declare const MOTION_MEMBERS: {
         readonly param: 1719;
         readonly type: "bool";
         readonly kind: "boolean";
-        readonly provenance: "apk";
+        readonly provenance: "verified";
         readonly description: string;
         readonly requires: readonly [1719];
         readonly write: (v: string | number | boolean, ctx: CommandContext) => Command;
@@ -367,7 +366,7 @@ export declare const MOTION_MEMBERS: {
         readonly param: 2706;
         readonly type: "bool";
         readonly kind: "boolean";
-        readonly provenance: "apk";
+        readonly provenance: "verified";
         readonly coerce: (raw: string | number | boolean) => boolean;
         readonly description: string;
         readonly requires: readonly [2706];

package/dist/model/capabilities/siren.d.ts

@@ -27,7 +27,7 @@ export declare const SIREN_CMD: {
     readonly ALARM_TEST: 1826;
     /** Manually stop a sounding alarm (app `APP_CMD_SIREN_SENSOR_MANUAL_STOP_ALARM`). */
     readonly MANUAL_STOP: 1871;
-    /** Station-family HomeBase duration alarm, verified live on T8010 (app `SET_TONE_FILE`). */
+    /** Station-family HomeBase duration alarm, verified live on T8010 and T8030 (app `SET_TONE_FILE`). */
     readonly HOMEBASE_TONE: 1201;
     /** HomeBase alarm volume percentage (app `CMD_SET_HUB_SPK_VOLUME`). */
     readonly HUB_SPK_VOLUME: 1235;

package/dist/model/param-dictionary.d.ts

@@ -5,10 +5,10 @@
  * Two namespaces (params are per-transport, NOT globally unique):
  *  - SECURITY_PARAMS — eufy P2P param space (ids 1000+). **Membership is the observation**: an id is
  *    listed only because the sweep saw it on a real owned device, so the id is real/accepted.
- *    `provenance` is the trust of the NAME/meaning: "verified" (our captures) > "apk" (the app's own
- *    decompiled constant name) > "guessed" (no name source — needs toggle-diff).
+ *    `provenance` is the trust of the NAME/meaning; the tiers are defined on `PropertySource` in
+ *    `types.ts`.
  *  - CLEAN_PARAMS — RoboVac Tuya DP space (ids 1 and above), names from the cloud
- *    `get_product_data_point` data_point_list (provenance "mega" — authoritative).
+ *    `get_product_data_point` data_point_list, hence provenance `mega`.
  *
  * Which models reported an id, and the capture that named it, are in the commit that adds the entry.
  */

package/dist/model/types.d.ts

@@ -104,18 +104,17 @@ export type ValueKind = KnownValueKind | (string & {});
  */
 export declare function isKnownValueKind(kind: ValueKind): kind is KnownValueKind;
 /**
- * Trust provenance of a property's `param_type` mapping, most-trusted first:
- *  - `mega`     — confirmed against the live mega API / a real device's reported params.
- *  - `apk`      — extracted from the v6 app itself (the ids the app actually sends — authoritative).
- *  - `verified` — confirmed by our own capture/observation.
- *  - `guessed`  — a plausible placeholder; lowest trust.
+ * How much a param's name and meaning can be trusted, most-trusted first. This is the one definition;
+ * the param dictionary and every `provenance` field use it.
+ *  - `mega`     — the vendor's cloud names it: its data-point catalog (`get_product_data_point`), or a
+ *                 reported value that matches what the cloud record already says (a model name or code).
+ *  - `verified` — confirmed on a real device by this project: our own capture or observation, or
+ *                 identified by someone who has the hardware.
+ *  - `apk`      — the v6 app's own decompiled constant name, not yet confirmed on a device.
+ *  - `guessed`  — no name source; a plausible placeholder until a toggle-diff settles it.
  *
- * This project never relies on a third-party reverse-engineering project as a source of trust —
- * every id/behavior we ship is grounded in the app's
- * own decompiled code (`apk`) or our own capture/observation (`verified`), never someone else's
- * unverified guess. Absent provenance is treated as `guessed`.
- *
- * Provenance of a property definition — an internal trust label used when curating the model.
+ * A third-party reverse-engineering project is never a source: every name we ship comes from the
+ * vendor's cloud, our own observation or the app itself. Absent provenance is treated as `guessed`.
  * @internal
  */
 export type PropertySource = "mega" | "apk" | "verified" | "guessed";

package/dist/transport/http/passport.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The `algo_ecdh` passport steps the eufy and Solix clients share byte for byte. Hosts, header sets, key
+ * caching, 2FA delivery and the `gtoken` id differ per app line and stay in each client.
+ */
+import { type SessionEntry } from "../../core/index.js";
+/** The credential fields every `/passport/login` body starts with; each client adds its own challenge fields. */
+export declare function loginCredentials(email: string, password: string, country: string): Record<string, unknown>;
+/**
+ * Read a decrypted `/passport/login` reply; `undefined` when it carries no id or no token. `twoFactorPending`
+ * is true while `fa_info.info` is non-empty and false once 2FA is satisfied.
+ */
+export declare function readLoginReply(data: Record<string, unknown>): {
+    userId: string;
+    accountUserId: string | undefined;
+    authToken: string;
+    geoKey: string | undefined;
+    tokenExpiresAt: number;
+    twoFactorPending: boolean;
+} | undefined;
+/** The headers that mark `encBody` as `algo_ecdh`-encrypted under `entry` and sign it. */
+export declare function signedHeaders(entry: SessionEntry, encBody: string): Record<string, string>;

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

@@ -3,12 +3,11 @@
  * eufy client uses.
  *
  * Why this is separate from the eufy device client: Solix shares Anker's `algo_ecdh` passport (so
- * {@link prepareKeyExchange} / {@link encryptLoginPassword} / {@link signRequest} are reused verbatim
- * for the login handshake) but exposes a different device backend — its own `app-name`, host, and
- * bootstrap key (`SOLIX_APP_NAME`, `SOLIX_DEFAULT_API_HOST`, {@link SOLIX_LOCAL_KEY_HEX}) —
- * and its authenticated resource reads are PLAIN JSON, carrying only the auth token and a
- * `gtoken = md5(user_id)`, with no per-request encryption or signature. This client therefore does
- * the encrypted passport handshake to obtain a token, then makes plain authenticated reads.
+ * {@link prepareKeyExchange} and the steps in `./passport.ts` are shared with it) but exposes a different device
+ * backend — its own `app-name`, host, and bootstrap key (`SOLIX_APP_NAME`, `SOLIX_DEFAULT_API_HOST`,
+ * {@link SOLIX_LOCAL_KEY_HEX}) — and its authenticated resource reads are PLAIN JSON, carrying only the auth token
+ * and a `gtoken = md5(user_id)`, with no per-request encryption or signature. This client therefore does the
+ * encrypted passport handshake to obtain a token, then makes plain authenticated reads.
  *
  * This is the wire client (transport layer): it returns the vendor's typed JSON as received. Building
  * those records into capability-driven `SolixDevice` models is the model layer's job — see

package/dist/transport/mqtt/secure-mqtt.d.ts

@@ -99,28 +99,35 @@ export declare class SecureMqtt extends EventEmitter implements RealtimeTranspor
     private open;
     /**
      * Subscribe every inbound leg this device's line uses (see `topics.ts` — one `/res` for most lines,
-     * four topics for `eufy_life`).
+     * four topics for `eufy_life` and the clean line).
      *
-     * The grants are INSPECTED, not assumed: AWS IoT answers a policy-denied filter with a
-     * SUBACK_FAILURE (`0x80`) grant rather than failing the SUBSCRIBE, so subscribing with a credential
-     * whose scope doesn't cover the topic looks identical to success and then delivers nothing. A denied
-     * topic is reported via `error` naming the credential scope; only an all-denied device throws, so a
-     * line that grants its state channel but refuses (say) the OTA leg still works.
+     * The grants are INSPECTED, not assumed: AWS IoT refuses a policy-denied filter with a
+     * {@link SUBACK_FAILURE} grant rather than failing the connection. A denied topic is reported via
+     * `error` naming the credential scope; only an all-denied device throws, so a line that grants its
+     * state channel but refuses (say) a business leg still works.
      */
     subscribeDevice(device: EufyDevice): Promise<void>;
     /**
      * Subscribe to explicit topic filters, returning the topics that were granted. A scope-denied filter
-     * comes back with SUBACK_FAILURE rather than an error (AWS IoT quirk), so it is dropped from the result
-     * instead of throwing — callers that need every leg check the returned list. Used by lines whose topic
-     * vocabulary isn't the eufy `subscribeTopics` shape (e.g. Anker Solix `dt/{app}/{pn}/{sn}`).
+     * is dropped from the result instead of throwing — callers that need every leg check the returned
+     * list. Used by lines whose topic vocabulary isn't the eufy `subscribeTopics` shape (e.g. Anker Solix
+     * `dt/{app}/{pn}/{sn}`).
      */
     subscribe(topics: string[]): Promise<string[]>;
     /**
-     * Split SUBACK grants into granted vs scope-denied topics. AWS IoT marks a policy-denied filter with a
-     * SUBACK_FAILURE (`0x80`) grant rather than failing the SUBSCRIBE, so the two subscribe paths share
-     * this split and layer their own policy (drop vs report) on top.
+     * Subscribe each filter in a SUBSCRIBE of its own and split the outcome into granted vs refused.
+     *
+     * One request per filter because the MQTT engine treats a SUBACK as all-or-nothing: one refused grant
+     * rejects the whole request, and it forgets EVERY filter of that request for resubscription after a
+     * reconnect — so a batch holding one denied leg would lose the granted legs on the next drop. Alone,
+     * a refused filter costs only itself. A rejection that carries no SUBACK is a transport failure and
+     * is thrown.
+     *
+     * The cost is one SUBSCRIBE and one SUBACK per filter instead of one per device — four for a
+     * four-leg line. They are sent concurrently, so the wall-clock cost is one round trip. Folding them
+     * back into one request brings back the lost resubscription.
      */
-    private partitionGrants;
+    private subscribeEach;
     /**
      * Publish a raw payload to an MQTT topic (the command leg — `cmd/{app}/{pn}/{sn}/req`). The `body`
      * is a pre-built envelope the caller supplies (the command router builds it). QoS 1 by default (the

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

@@ -59,6 +59,12 @@ export interface AdtsHeader {
  * nothing about whether the frame's payload has arrived yet; that is the scanner's job.
  */
 export declare function parseAdtsHeader(buf: Buffer, offset?: number): AdtsHeader | undefined;
+/**
+ * The 7-byte ADTS header (no CRC, buffer fullness "variable") that frames one raw AAC-LC, 16 kHz, mono
+ * access unit of `payloadLength` bytes, so that header and payload together read back through
+ * {@link parseAdtsHeader} as a supported frame.
+ */
+export declare function buildAdtsHeader(payloadLength: number): Buffer;
 /**
  * Whether a header describes the audio parameters the device's path is fixed at — AAC-LC, 16 kHz,
  * mono. A stream at any other rate or channel count is rejected rather than resampled: the device has

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

@@ -22,6 +22,11 @@ export declare const ResponseMessageType: {
     readonly LOOKUP_ADDR: Buffer<ArrayBuffer>;
     readonly LOOKUP_ADDR2: Buffer<ArrayBuffer>;
     readonly CAM_ID: Buffer<ArrayBuffer>;
+    /**
+     * The device's own address record, sent in answer to CHECK_CAM ahead of CAM_ID: its 20-byte device id, one
+     * record in `encodeSelfAddress`'s shape naming the address it answers from, then 8 zero bytes (44-byte payload).
+     */
+    readonly CAM_ADDR: Buffer<ArrayBuffer>;
     readonly TURN_SERVER_CAM_ID: Buffer<ArrayBuffer>;
     readonly PING: Buffer<ArrayBuffer>;
     readonly PONG: Buffer<ArrayBuffer>;
@@ -149,6 +154,14 @@ export declare function buildStringCommandPayload(value: string, channel?: numbe
  * length prefix ({@link stringWithLength}).
  */
 export declare function buildIntStringCommandPayload(value: number, valueSub: number, strValue: string, channel?: number, key?: Buffer, encType?: number): Buffer;
+/**
+ * Build a **string-pair** command body: five zero bytes, then `strValue` and `strValueSub`, each in the
+ * 128-byte-chunk length form ({@link stringWithLength}), AES-128-ECB encrypted (level-1) like
+ * {@link buildStringCommandPayload} when `key` is given. `CMD_DOWNLOAD_VIDEO` (1024) takes this shape on a
+ * HomeBase 2: `strValue` = the recording's path on the station, `strValueSub` = the station admin
+ * `account_id`, on the camera's channel.
+ */
+export declare function buildStringPairCommandPayload(strValue: string, strValueSub: string, channel?: number, key?: Buffer, encType?: number): Buffer;
 /**
  * Build a command body around an ALREADY-encrypted (or plaintext) `data` buffer with an explicit
  * `signCode` — used for level-2 (`signCode 8`, AES-256-GCM) commands like the media-start 1350 the

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

@@ -121,6 +121,8 @@ export declare class P2PCommandRouter {
     private readonly talkbacks;
     /** cipher_id → ECC private key (one eufylife get_ciphers call per cipher), shared across (re)opens. */
     private readonly cipherKeyCache;
+    /** The recording download in flight per station; a station serves one at a time. */
+    private readonly recordingDownloads;
     constructor(deps: P2PRouterDeps);
     /** Forward one P2P failure once even when both the session listener and startup waiter observe it. */
     private reportError;
@@ -237,6 +239,12 @@ export declare class P2PCommandRouter {
      * while its own session is still serving.
      */
     private makeSession;
+    /**
+     * The ECC private key of `cipherId`, from the router's cache or one `get_ciphers` call. When the cloud
+     * answers with another cipher, that one is used and traced on `session`. Only a successful lookup is
+     * cached.
+     */
+    private cipherKeyFor;
     /**
      * Open (or reuse) a station's P2P session and await its completed handshake. An optional abort only
      * stops this wait; session ownership remains with {@link SessionManager} and its normal teardown.
@@ -269,6 +277,27 @@ export declare class P2PCommandRouter {
      * start has no level-1 form for.
      */
     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.
+     */
+    private downloadsRecordings;
+    /**
+     * 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.
+     */
+    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.
+     */
+    private startRecordingDownload;
     /**
      * Open a {@link Talkback} on a device's camera channel.
      *

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

@@ -95,6 +95,8 @@ export declare class P2PSession extends EventEmitter {
     private connected;
     private connecting;
     private closed;
+    /** Whether a short receive buffer has been reported, so a reconnect does not repeat the same warning. */
+    private receiveBufferReported;
     private connectAddress?;
     private seqNumber;
     /**
@@ -121,8 +123,8 @@ export declare class P2PSession extends EventEmitter {
     private audioStalled;
     private audioRetransmitTimer?;
     private lastPongData?;
-    /** When this connection last received a PONG — `undefined` until the first, see {@link pathSilentMs}. */
-    private lastPongAt?;
+    /** When the selected peer last answered outbound P2P traffic on this connection. */
+    private lastPeerAt?;
     /** Whether the silence has already been stated, so it is traced once per connection rather than per read. */
     private pathStaleTraced;
     private lookupTimer?;
@@ -134,7 +136,10 @@ export declare class P2PSession extends EventEmitter {
     private cloudLookup?;
     /** Local outbound IPv4 reported inside LOOKUP_WITH_KEY requests. */
     private selfHost?;
-    /** In-flight multi-datagram frame per data channel (see onData). */
+    /**
+     * In-flight multi-datagram frame per data channel (see reassemble): the payload gathered so far under its
+     * parsed header, or, without a header, the start of a frame header cut by the datagram boundary.
+     */
     private readonly pendingByDataType;
     /** Last delivered datagram sequence number per data type. */
     private readonly lastSeqByType;
@@ -182,15 +187,15 @@ export declare class P2PSession extends EventEmitter {
     /**
      * How long this connection's path has been silent, or nothing where it has never answered.
      *
-     * A PONG is the station stating that the path is alive. `undefined` is neither alive nor dead: it is a station
-     * that has said nothing either way.
+     * PONG and ACK from the selected peer prove the path answers outbound traffic. `undefined` means no such reply
+     * has arrived since connection, so silence alone does not establish a stale path.
      */
     get pathSilentMs(): number | undefined;
     /**
      * Whether this path can still be committed to, on the evidence the heartbeat gives.
      *
-     * False where a pong arrived and then stopped for {@link PATH_SILENCE_MS}. A station that has never ponged is
-     * not known to be dead, so it answers true.
+     * False where selected-peer replies arrived and then stopped for {@link PATH_SILENCE_MS}. A connection with
+     * no post-connect reply is not known to be dead, so it answers true.
      *
      * Traces the silence once per connection, on the read that first observes it.
      */
@@ -271,6 +276,14 @@ export declare class P2PSession extends EventEmitter {
      */
     private decryptLevel2;
     get isConnected(): boolean;
+    /**
+     * Ask the OS for {@link RECEIVE_BUFFER_BYTES} on a bound socket, and warn once per session when it grants
+     * less or refuses.
+     *
+     * The request is made here rather than through `createSocket`'s `recvBufferSize`: Node applies that option
+     * 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. */
     connect(): Promise<void>;
     /** Cached across every `P2PSession` in this process — the local outbound IPv4 doesn't vary by
@@ -313,6 +326,9 @@ export declare class P2PSession extends EventEmitter {
      * straddling a level-2 wait on a camera whose failure to deliver video had a separate cause, and did not
      * recur across later probes of it. Correlate an unmodelled type against a WORKING session before reading it
      * as a cause.
+     *
+     * CAM_ADDR is recognised and dropped: it names the address the device is already answering from, and the
+     * CAM_ID that follows it is what completes the connect.
      */
     private onMessage;
     private beginCheckCam;
@@ -397,6 +413,8 @@ export declare class P2PSession extends EventEmitter {
      * `strValue` (admin `account_id`). See {@link buildIntStringCommandPayload}. Fire-and-forget.
      */
     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;
     /**
      * 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
@@ -497,11 +515,6 @@ export declare class P2PSession extends EventEmitter {
      * camera is selected by `mChannel` (= the device's `device_channel`) AND the frame-header channel.
      */
     private sendMediaPayloadLevel2;
-    /**
-     * Encrypt a level-2 command body (signCode 8): `tag(16) ‖ nonce(12) ‖ [seq,03,02,01](4) ‖
-     * ciphertext`, AES-256-GCM under the negotiated session key, AAD "eufy security". Inverse of
-     * `decryptLevel2`. The 4-byte sub-header is cleartext (skipped on decrypt); `seq` is a counter.
-     */
     /**
      * Decode a `CMD_VIDEO_FRAME` (1300) payload into clean Annex-B H.264 (the 22-byte frame header
      * stripped). Reversed from the V6 app + live H.264 captures: the 22-byte header is
@@ -525,6 +538,11 @@ export declare class P2PSession extends EventEmitter {
      * key. Lazily generates a keypair; `rsaPrivateKey` decrypts the media key the station returns.
      */
     private rsaModulus;
+    /**
+     * Encrypt a level-2 command body (signCode 8): `tag(16) ‖ nonce(12) ‖ seq(4) ‖ ciphertext`,
+     * AES-256-GCM under the negotiated session key, AAD "eufy security". Inverse of `decryptLevel2`.
+     * The 4-byte sub-header is cleartext (skipped on decrypt); `seq` counts up from {@link LEVEL2_SEQ_BASE}.
+     */
     private encryptLevel2;
     /** Send a no-arg command frame (e.g. CMD_GATEWAYINFO) on a channel (default: the station channel). */
     private sendCommand;
@@ -548,6 +566,10 @@ export declare class P2PSession extends EventEmitter {
      * The HomeBase streams back `CMD_DATABASE` (1306) frames `{cmd:10000,count,data:[…]}`,
      * level-1-encrypted — decoded and emitted as `dbChunk` (decrypted text) per frame.
      * Tables: `familiar_faces`, `person_basic_info`, `event_person_list`, `history_record_info`.
+     *
+     * Throws while a {@link readDatabase} is accumulating: every table answers `{data:[…]}` and the
+     * frames tie no chunk to its request, so a second query's reply would be assembled into the first
+     * one's buffer and answered as its rows.
      */
     queryDatabase(table: string, opts?: {
         accountId?: string;
@@ -575,6 +597,25 @@ export declare class P2PSession extends EventEmitter {
         accountId?: string;
         channel?: number;
     }): void;
+    /**
+     * Query one on-station table and answer its rows, once the reply is whole.
+     *
+     * The request half of {@link queryDatabase} with its reply assembled: `CMD_DATABASE` arrives as
+     * several frames whose decrypted text is a fragment of one document, so the fragments are
+     * accumulated here and scanned after each one. Answers that document's `data` rows. Rejects when
+     * `signal` aborts, and when `timeoutMs` (default {@link DB_TABLE_TIMEOUT_MS}) elapses with no
+     * complete reply.
+     *
+     * 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.
+     */
+    readDatabase(table: string, opts?: {
+        accountId?: string;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<unknown[]>;
+    /** Whether a {@link readDatabase} is accumulating; see {@link queryDatabase} for what it bars. */
+    private dbReadInFlight;
     /**
      * Request the **face feature rows** over P2P (`face_feature_info`, inner `cmd 10000`). Each row
      * carries `{person_id, face_name, face_id, face_picture_content, face_feature_file_path}` — where
@@ -643,7 +684,13 @@ export declare class P2PSession extends EventEmitter {
      */
     private abandonHole;
     private clearReorderTimer;
-    /** Reassemble one in-sequence datagram body into logical frames. */
+    /**
+     * Reassemble one in-sequence datagram body into logical frames.
+     *
+     * Frames are packed back to back, so a frame header can itself be cut by a datagram boundary. The start
+     * of a header left at the end of a datagram is carried into the next one rather than discarded; dropping
+     * it would lose that frame and every frame after it until a datagram happened to begin on a header.
+     */
     private reassemble;
     /**
      * Forget where each data type's sequence numbering had reached, and drop any half-reassembled frame.

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

@@ -0,0 +1,54 @@
+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. */
+export declare const RECORDING_DATA_TYPE = 3;
+/**
+ * Most frame bytes a transfer holds. The station sends faster than real time, so the time bounds alone do
+ * not bound memory; an event recording is far below this.
+ */
+export declare const MAX_TRANSFER_BYTES: number;
+/** One recording frame as received, in arrival order. */
+export interface RecordingFrame {
+    commandId: number;
+    signCode: number;
+    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.
+ */
+export declare function homeBase2RecordingPath(channel: number, recording: string): string | undefined;
+/** One recording transfer on a station session. */
+export interface RecordingTransfer {
+    /** The recording's frames, in arrival order. Rejects as {@link receiveRecording} describes. */
+    frames: Promise<RecordingFrame[]>;
+    /** Resolves once the station has stopped sending this recording, which can be after `frames` rejected. */
+    drained: Promise<void>;
+}
+/**
+ * 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.
+ *
+ * `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
+ * {@link IDLE_END_MS} silence, on `timeoutMs` or on {@link MAX_TRANSFER_BYTES}. An abort rejects it at once
+ * with the signal's reason. After a time bound, the byte ceiling or an abort, the transfer stops collecting
+ * but keeps listening until the station finishes or goes quiet, and only then resolves `drained`.
+ */
+export declare function receiveRecording(session: P2PSession, request: {
+    path: string;
+    accountId: string;
+    channel: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): RecordingTransfer;
+/**
+ * Decode a recording's frames, in arrival order, into elementary streams. 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.
+ */
+export declare function decodeRecording(frames: readonly RecordingFrame[], eccPrivateKeyHex: string): RecordingDownload;

package/dist/transport/p2p/shared-live-source.d.ts

@@ -16,7 +16,7 @@ export interface SharedLiveSourceOptions {
     makeStream: (ctx: {
         reassertWanted: () => boolean;
     }) => LiveStreamHandle;
-    /** No-consumer grace before teardown (default 8000ms). Distinct from the stream's keepalive. */
+    /** No-consumer grace before teardown (default 8000ms; 0 schedules teardown next tick). Distinct from the stream's keepalive. */
     lingerMs?: number;
     /** Per-consumer bounded queue depth; overflow → drop-to-keyframe (default 900 ≈ 30s @ 30fps). */
     maxQueue?: number;

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

@@ -1,3 +1,5 @@
+/** AAD used for the AES-256-GCM body cipher of every video frame, and of a recording's audio. */
+export declare const VIDEO_GCM_AAD: Buffer<ArrayBuffer>;
 /** Parsed fields of a `CMD_VIDEO_FRAME` 22-byte header. */
 export interface VideoFrameHeader {
     /**

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

@@ -24,6 +24,8 @@ export declare class StoredImageCache {
     clear(): void;
     private pump;
     private complete;
+    /** Schedule the next attempt after a 404; answers whether one was scheduled. */
+    private retryLater;
     private isValidJpeg;
     private diagnose;
 }

package/package.json

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