@mega-yfue/eufy-sdk 0.6.0-beta.14 → 0.6.0-beta.16

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, StationFace, StationFacesOptions, WaitForRealtimeOptions } from "./types.js";
-export type { EufyMegaOptions, EufyMegaEvent, EufyMegaEventMap, AnyDeviceEvent, DeviceState, RealtimePlaneReadiness, RealtimeReadiness, StationFace, StationFacesOptions, WaitForRealtimeOptions, } from "./types.js";
+import type { EufyMegaOptions, EufyMegaEvent, EufyMegaEventMap, DeviceState, RealtimeReadiness, StationFace, StationReadOptions, WaitForRealtimeOptions } from "./types.js";
+export type { EufyMegaOptions, EufyMegaEvent, EufyMegaEventMap, AnyDeviceEvent, DeviceState, RealtimePlaneReadiness, RealtimeReadiness, StationFace, StationReadOptions, 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;
@@ -54,6 +54,12 @@ export declare class EufyMega extends EventEmitter {
     /** Shared in-flight/settled `startMqtt()` promise PER SCOPE — so realtime bring-up and an on-demand
      * publish await the SAME fully-connected transport instead of racing (and never open two). */
     private readonly mqttReady;
+    /**
+     * Serials {@link subscribeMqttDevices} has subscribed or is subscribing, per transport, so a later pass
+     * subscribes only devices that transport has not carried yet. Keyed by transport, so a new connection
+     * starts empty.
+     */
+    private readonly mqttSubscribed;
     /** Device list/record/capability resolution + the frame→caps cache. */
     private readonly registry;
     private pushClient?;
@@ -385,7 +391,9 @@ export declare class EufyMega extends EventEmitter {
     /**
      * On a successful login, kick off auto-realtime (unless `autoRealtime:false`). Fire-and-forget so
      * `login()` returns as soon as the session is ready — realtime channels come up in the background and
-     * surface failures via `error`. Idempotent through the retained generation promise.
+     * surface failures via `error`. Idempotent through the retained generation promise. A login for a
+     * different account drops every stored image; one for the same account drops only the lifecycle
+     * failures recorded against the session it replaces.
      */
     private afterLogin;
     /**
@@ -627,6 +635,12 @@ export declare class EufyMega extends EventEmitter {
      * device absent from the previous pass is skipped — first sight is discovery, not a transition;
      * {@link deviceState} answers an initial reading.
      *
+     * A device with changed params is re-resolved by {@link widenCapabilities} once per pass, however many
+     * of its params moved, since each re-resolution is a cloud param-list read.
+     *
+     * Then brings the secure-MQTT plane up to the roster ({@link syncMqttRoster}): the startup bring-up
+     * sized it from the roster at login, which is empty when the cloud was unreachable then.
+     *
      * Then re-reads every Tuya clean-line robot from the Tuya cloud ({@link readTuyaDevices}): its state
      * is not in the cloud record this pass diffs and no live channel carries it, so the poll is where it
      * stays fresh. That read runs after the `try`, not inside it, so a cloud error on the list diff does
@@ -813,11 +827,20 @@ export declare class EufyMega extends EventEmitter {
     /**
      * Subscribe the devices on one credential scope; a failing subscribe is reported, not fatal (one
      * unreachable device must not stop the rest of the roster from coming up).
+     * A device is recorded in that transport's {@link mqttSubscribed} entry before its subscribe is awaited,
+     * whatever the outcome, so a pass running alongside or after skips it: each device is attempted once
+     * per transport.
      *
      * A Tuya clean-line device (`eufy_home_tuya`) is not subscribed: its state lives on the Tuya cloud,
      * and the broker refuses its `eufy_home` topics on every credential.
      */
     private subscribeMqttDevices;
+    /**
+     * Start every credential scope the roster now needs and has no transport for, and subscribe the
+     * devices that joined a scope already up — each scope's failure reported, not thrown. A no-op once
+     * the realtime generation is superseded or was never started.
+     */
+    private syncMqttRoster;
     /**
      * Send whatever a device's capabilities want sent once its realtime channel is up — for a line whose
      * state is pushed on change with no heartbeat, the request that makes its state readable before the
@@ -838,19 +861,45 @@ export declare class EufyMega extends EventEmitter {
      */
     getP2pSessions(): Map<string, P2PSession>;
     /**
-     * The people enrolled on a station, read from its own `person_basic_info` table over P2P.
+     * The people enrolled on a station, read from its own `person_basic_info` table through
+     * {@link readStationTable}.
      *
      * 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.
+     * Resolves with the rows the station returned that are objects. Rejects as {@link readStationTable}
+     * does.
      *
      * `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[]>;
+    getStationFaces(stationSn: string, opts?: StationReadOptions): Promise<StationFace[]>;
+    /**
+     * The rows of one of a station's own tables (`history_record_info`, `person_basic_info`, …), read over
+     * the transport the station speaks: the control channel of a HomeBase S1 Pro (T9000), P2P for any
+     * other station. The query is the table's whole content; the rows are the station's, shaped by it.
+     *
+     * Resolves with the rows the station returned. Rejects on a serial not in the device list, on a record
+     * stating no `admin_user_id`, on a station that cannot be reached, on a query the station refuses, and
+     * on the reply not arriving in time. Assembling the reply is the transport's; this resolves which
+     * station, which transport and which account id.
+     */
+    readStationTable(stationSn: string, table: string, opts?: StationReadOptions): Promise<unknown[]>;
+    /**
+     * One image stored on a HomeBase S1 Pro (T9000), by the on-station path a table row names
+     * (`thumb_path`, …), read over the station's control channel.
+     *
+     * Resolves with the image bytes as the station holds them. Rejects on a serial not in the device list,
+     * on a record stating no `admin_user_id`, on a station other than a T9000, on a station that cannot be
+     * reached, and on the reply not arriving in time. Fetching the image is the transport's; this resolves
+     * which station and which account id.
+     */
+    readStationImage(stationSn: string, filePath: string, opts?: StationReadOptions): Promise<Buffer>;
+    /**
+     * The station a database read goes to, its `admin_user_id` and, for a T9000, its RTC route. Throws,
+     * prefixed with `op`, on a serial the device list does not carry and on a record stating no admin id.
+     */
+    private stationReadTarget;
     /** The station's own `admin_user_id`, which its database refuses the query without. */
     private adminUserIdOf;
     /**
@@ -962,6 +1011,9 @@ export declare class EufyMega extends EventEmitter {
      * Returns the connected client rather than installing it. Registration can outlive a `disconnect()`,
      * and {@link ensureRealtime} owns the decision of whether a finished bring-up is still the current
      * one — so this never overwrites a channel a later login already brought up.
+     *
+     * Persisting the seen ids after each push reports a failed `save` through `error` rather than throwing:
+     * the push handler runs inside the MCS socket's `data` callback, where a throw is an uncaught exception.
      */
     private startPush;
     /**

package/dist/client/types.d.ts

@@ -240,9 +240,9 @@ export interface StationFace {
     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. */
+/** How long to wait for a station's reply to a read, and how to give up early. */
+export interface StationReadOptions {
+    /** Default 15s. A station that will not answer says nothing. */
     timeoutMs?: number;
     signal?: AbortSignal;
 }

package/dist/core/contracts.d.ts

@@ -852,7 +852,9 @@ export interface MediaProvider {
      * {@link ReceivedVideoFrame} envelopes whose original source-arrival time survives retained replay.
      * Raw mode ignores arrivalTime. Audio is available separately through {@link live} or muxed through
      * {@link recordFragments}; it is never interleaved into raw video. The caller owns the Readable's
-     * lifetime, and destroying it releases the shared pull.
+     * lifetime, and destroying it releases the shared pull. On a battery-budgeted source the Readable
+     * emits a `budget` event with a {@link StreamBudgetNotice}; unless `extend()` is called within its
+     * grace, the Readable ends.
      */
     openReadable?(opts?: {
         objectMode?: boolean;

package/dist/core/store.d.ts

@@ -48,7 +48,18 @@ export declare class MemorySessionStore<T = PersistedSession> implements Session
     save(s: T): void;
     clear(): void;
 }
-/** JSON-file store, e.g. new FileSessionStore("./.eufy-session.json"). */
+/**
+ * JSON-file store, e.g. new FileSessionStore("./.eufy-session.json").
+ *
+ * `save` resolves a symlinked path to its real file (the file a dangling symlink names, created with its
+ * directory), writes a fresh owner-only (`0o600`) temp file under a random name beside that file and
+ * renames it over it, so where the directory allows it the file on disk is always a complete record — the
+ * old one until the rename, the new one after — and the symlink itself stays in place. When the directory
+ * refuses the temp file or the rename (`EACCES`, `EPERM`, `EBUSY`, `EXDEV`, `EROFS`: a read-only directory
+ * around a writable file, a single-file bind mount), `save` rewrites the file in place instead, which is
+ * not atomic and keeps an existing file's mode. The atomic path always leaves `0o600`, whatever mode an
+ * existing file had. Any other failure removes the temp file and throws.
+ */
 export declare class FileSessionStore<T = PersistedSession> implements SessionStore<T> {
     private readonly path;
     constructor(path: string);