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

package/dist/client/eufy-mega.d.ts

@@ -20,8 +20,8 @@ import { type P2PSession } from "../transport/p2p/p2p-session.js";
 import { type CleanRecordPage } from "../model/clean-records.js";
 import { type AvailabilityObservation, type EufyDevice } from "../core/types.js";
 import { Device, type DeviceInspection } from "../model/index.js";
-import type { EufyMegaOptions, EufyMegaEvent, EufyMegaEventMap, DeviceState, RealtimeReadiness, WaitForRealtimeOptions } from "./types.js";
-export type { EufyMegaOptions, EufyMegaEvent, EufyMegaEventMap, AnyDeviceEvent, DeviceState, RealtimePlaneReadiness, RealtimeReadiness, WaitForRealtimeOptions, } from "./types.js";
+import type { EufyMegaOptions, EufyMegaEvent, EufyMegaEventMap, DeviceState, RealtimeReadiness, StationFace, StationFacesOptions, WaitForRealtimeOptions } from "./types.js";
+export type { EufyMegaOptions, EufyMegaEvent, EufyMegaEventMap, AnyDeviceEvent, DeviceState, RealtimePlaneReadiness, RealtimeReadiness, StationFace, StationFacesOptions, WaitForRealtimeOptions, } from "./types.js";
 export interface EufyMega {
     on<E extends EufyMegaEvent>(event: E, listener: (...args: EufyMegaEventMap[E]) => void): this;
     once<E extends EufyMegaEvent>(event: E, listener: (...args: EufyMegaEventMap[E]) => void): this;
@@ -764,6 +764,22 @@ export declare class EufyMega extends EventEmitter {
      * every event the station's own session already delivers.
      */
     getP2pSessions(): Map<string, P2PSession>;
+    /**
+     * The people enrolled on a station, read from its own `person_basic_info` table over P2P.
+     *
+     * The cloud roster (`api.getFaces()`) answers empty for an account that keeps its faces on the
+     * station, because they were never uploaded — the station holds them.
+     *
+     * Resolves with the rows the station returned. Rejects on a station that cannot be reached, on a
+     * record stating no `admin_user_id`, and on the reply not arriving whole in time. Assembling that
+     * reply is `P2PSession.readDatabase`'s; this resolves which station and which account id.
+     *
+     * `stranger<n>` names are the station's own placeholders for a face nobody has named, and are
+     * returned as they arrive; a caller that wants only named people filters them.
+     */
+    getStationFaces(stationSn: string, opts?: StationFacesOptions): Promise<StationFace[]>;
+    /** The station's own `admin_user_id`, which its database refuses the query without. */
+    private adminUserIdOf;
     /**
      * The liveness facts for one device — see {@link DeviceState}. Facts, not an `online` verdict: "how
      * long is too long" is a threshold that belongs to the caller, and it differs per device class.
@@ -871,7 +887,10 @@ export declare class EufyMega extends EventEmitter {
      * one — so this never overwrites a channel a later login already brought up.
      */
     private startPush;
-    /** Admit only exact, account-known devices with resolved snapshot evidence into the passive store. */
+    /**
+     * Admit only exact, account-known devices with resolved snapshot evidence into the passive store; a
+     * station-only candidate is admitted under the event's device serial.
+     */
     private observeStoredImage;
     /**
      * Tear down every realtime channel: close the secure-MQTT transport, all P2P sessions, and the FCM

package/dist/client/types.d.ts

@@ -221,6 +221,31 @@ export interface DeviceState {
      */
     lastSeenMs?: number;
 }
+/**
+ * One person enrolled on a station, as its `person_basic_info` table states them.
+ *
+ * The station's own table, not the cloud's: an account that keeps its faces on the station never
+ * uploaded them, so the cloud roster answers empty for it while this answers the household.
+ *
+ * `person_id` is the id an `IDENTITY_PERSON_DETECTION` push carries, which is what makes a detection
+ * nameable. Every field is optional because the row is the station's to shape — an absent one is a
+ * column that row did not carry, never a default — and unrecognised columns are kept verbatim, so a
+ * station that states more than this is not truncated by it. Keys are the table's own, uncased.
+ */
+export interface StationFace {
+    person_id?: number;
+    /** The name this person was enrolled under. `stranger<n>` is the station's own placeholder. */
+    name?: string;
+    relation?: number | string;
+    group_id?: number | string;
+    [column: string]: unknown;
+}
+/** How long to wait for a station's database reply, and how to give up early. */
+export interface StationFacesOptions {
+    /** Default 15s. A full table is a handful of frames; a station that will not answer says nothing. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
 /**
  * A single semantic event tagged with its name — the payload of the catch-all `"event"` listener.
  * A discriminated union over {@link DeviceEventMap}, so switching on `e.eventName` narrows `e` to that

package/dist/core/contracts.d.ts

@@ -150,6 +150,39 @@ export declare class DeviceChannelUnresolvedError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * Why {@link MediaProvider.downloadRecording} returned no recording.
+ *
+ * - `invalid-recording` — the recording name is not one the station could hold.
+ * - `key-unavailable` — the key the recording was stored under could not be obtained.
+ * - `no-data` — the station sent nothing within the wait.
+ * - `incomplete` — the transfer ended before the station's finish frame.
+ * - `undecodable` — data arrived but no video frame could be decoded from it.
+ */
+export type RecordingDownloadFailureReason = "invalid-recording" | "key-unavailable" | "no-data" | "incomplete" | "undecodable";
+/** Thrown by {@link MediaProvider.downloadRecording} when no recording could be returned. */
+export declare class RecordingDownloadError extends Error {
+    readonly reason: RecordingDownloadFailureReason;
+    constructor(reason: RecordingDownloadFailureReason, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A recording downloaded from the station, as elementary streams.
+ *
+ * `video` is Annex-B H.264 in decode order, `audio` AAC-LC 16 kHz mono in ADTS framing (absent when the
+ * recording carried none that could be decoded). `frames` counts the distinct video frames received,
+ * `missingFrames` the ones the camera numbered but that never arrived, and `durationMs` spans the first
+ * to the last received frame by the camera's own timestamps; `fps` is derived from those two stamps.
+ */
+export interface RecordingDownload {
+    video: Buffer;
+    audio?: Buffer;
+    frames: number;
+    missingFrames: number;
+    durationMs: number;
+    fps: number;
+}
 /**
  * How a live stream ended before its first video keyframe: the warm-up deadline elapsed, the source
  * reported an error, or the source ended on its own.
@@ -684,8 +717,8 @@ export interface SharedSourceHints {
      */
     powered?: "wired" | "battery";
     /**
-     * Seconds of already-captured media the pull retains for a later drain; `0`, absent, non-finite and
-     * negative values retain none.
+     * Seconds of already-captured media the pull retains for a later drain; `0`, absent, non-finite,
+     * negative, and windows longer than 2,147,483,647 ms retain none.
      *
      * Retention costs memory on every frame and only a caller knows whether anything will drain it, so it
      * is never assumed. Media can only be retained while the pull is running, so a window answers "what did
@@ -804,6 +837,16 @@ export interface MediaProvider {
     talkback?(opts?: {
         encoder?: AacEncoder;
     } & SharedSourceHints): Promise<TalkbackHandle>;
+    /**
+     * Download one recording the camera's station stored, identified by the recording name and cipher id of
+     * the event. One download runs at a time per station. Rejects with {@link RecordingDownloadError}.
+     * Optional, and absent on a camera whose station's recording download is unverified.
+     */
+    downloadRecording?(opts: {
+        recording: string;
+        cipherId: number;
+        timeoutMs?: number;
+    } & AbortableCall): Promise<RecordingDownload>;
     /**
      * Generic P2P request/reply query: send a `SET_PAYLOAD` sub-command and resolve with the reply
      * frame's `payload` (the reply whose `cmd` echoes `subCmd`). Transport-only — the caller owns the