@mega-yfue/eufy-sdk 0.4.0-beta.15 → 0.4.0-beta.17

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

@@ -154,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

@@ -413,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
@@ -564,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;
@@ -591,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

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/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/package.json

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