@mega-yfue/eufy-sdk 0.6.0-beta.3 → 0.6.0-beta.30

package/dist/client/device-registry.d.ts

@@ -248,6 +248,12 @@ export declare class DeviceRegistry {
      * for an expired token is the same lie {@link getDevices} stopped telling, one level down.
      */
     refreshedList(sn: string): Promise<EufyDevice | undefined>;
+    /**
+     * Record that `sn` was heard on a realtime wire at `atMs`, advancing its {@link EufyDevice.lastSeenMs}.
+     *
+     * Only ever moves the time forward, and survives a {@link getDevices} rebuild.
+     */
+    markSeen(sn: string, atMs: number): void;
     /**
      * Record state a device reported over its realtime wire, merging into whatever it last reported.
      *

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?;
@@ -123,6 +129,20 @@ export declare class EufyMega extends EventEmitter {
     private readonly pollTimer;
     /** Armed while a failed push bring-up waits to be retried; cancelled by {@link disconnect}. */
     private readonly pushRetryTimer;
+    /**
+     * Per wired station, the pending reopen of its session and the pause before the next one; see
+     * {@link reopenWiredStation}. Dropped for a station when its session connects, and wholly by
+     * {@link disconnect}.
+     */
+    private readonly stationReopens;
+    /**
+     * Refuse the one misnamed option that misroutes silently. `country` is not read — the account country
+     * is {@link EufyMegaOptions.countryCode}, which defaults to `"US"` — so a caller that passes `country`
+     * has it ignored. We throw only for the case that changes routing: a non-`"US"` `country` with no
+     * `countryCode`, which would run on the US shard (login succeeds, but the house list comes back an empty
+     * placeholder). `country: "US"` already matches the default route, so it is left to pass through.
+     */
+    private static assertCountryOption;
     constructor(opts: EufyMegaOptions);
     /**
      * Builds the inbound listener that converts ThingClips DP maps to realtime capability state.
@@ -307,7 +327,17 @@ export declare class EufyMega extends EventEmitter {
      * manager's own log, since by then nothing is waiting to receive it.
      */
     private recycleStandaloneSession;
-    /** Reopen a wired station that {@link recycleStandaloneSession} closed, while the generation that warmed it is current. */
+    /**
+     * Reopen a wired station's session while the generation that warmed it is current: after
+     * {@link recycleStandaloneSession} closed it, after it closed on its own, or after its warm-up failed.
+     *
+     * A wired station's session is the persistent one realtime start opened, so a station left without one
+     * receives nothing until a command dials it again. The first reopen runs at once; one that fails is
+     * retried after {@link STATION_REOPEN_MIN_MS}, doubling up to {@link STATION_REOPEN_MAX_MS}, until the
+     * session connects or the generation ends. One reopen is pending per station at a time, and each failure
+     * is reported once, by {@link P2PCommandRouter.ensureStation}. A HomeBase S1 Pro (T9000) answers no P2P
+     * lookup, so it is never reopened.
+     */
     private reopenWiredStation;
     /**
      * Whether the DECODED property now reads what the write asked for.
@@ -333,6 +363,8 @@ export declare class EufyMega extends EventEmitter {
      * fans same-kind sensors out by channel, so the resolved serial is folded in; a payload's own
      * fields still win on conflict.
      *
+     * A station's camera-info table lands per channel, each channel's params on the device attached there.
+     *
      * Params the station volunteered land as device state first. They arrive in the cloud record's own
      * `param_type → value` shape, so no capability has to claim an id it does not own, and the reads
      * they back stop waiting for the next cloud poll. A capability decode follows for the frames that
@@ -385,7 +417,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;
     /**
@@ -458,7 +492,8 @@ export declare class EufyMega extends EventEmitter {
     private rtcRouteFor;
     /**
      * The RTC media provider for a station on a media-track route, or a camera attached to a T9000 whose
-     * `device_channel` resolves back to it on the station; `undefined` otherwise, unless an NVR camera has its own dedicated media call.
+     * `device_channel` resolves back to it on the station; `undefined` otherwise. A camera attached to a T8N00 gets the
+     * NVR's dedicated media call when {@link isNvrMediaCamera} admits it.
      */
     private rtcMediaFor;
     /**
@@ -534,6 +569,8 @@ export declare class EufyMega extends EventEmitter {
      * first announces it and the others stay silent. Its timing says only when a caller happened to read; the
      * value is the news. It applies what the device volunteered over realtime on top of the cloud half, which
      * the registry keeps apart, so it can neither revert nor announce a revert of a report already landed.
+     * Nothing awaits that refresh, so its failure is reported like the other background paths' — a dead
+     * token as `sessionExpired`, anything else as `error` — and the read keeps its last-known value.
      *
      * The `Device` returned is held WEAKLY: it is what the inbound paths announce against, so a caller that
      * wants property changes for a serial keeps its own reference. Dropping it stops the announcements, not
@@ -624,6 +661,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
@@ -737,7 +780,9 @@ export declare class EufyMega extends EventEmitter {
      */
     keepStationWarm(stationSn: string): () => void;
     /** Eagerly open P2P sessions for WIRED stations only (persistent — they don't drain). Battery
-     *  stations stay closed until an on-demand open. Best-effort per station. */
+     *  stations stay closed until an on-demand open, and a HomeBase S1 Pro (T9000), which answers no P2P
+     *  lookup and is driven over RTC, is never opened here. Best-effort per station: one that fails is
+     *  handed to {@link reopenWiredStation}. */
     private warmWiredP2P;
     /**
      * A station's power tier for the P2P lifecycle: a HomeBase/station is `"wired"` (persistent); a
@@ -753,10 +798,11 @@ export declare class EufyMega extends EventEmitter {
      * semantic event in — so a stream or talkback opened right after a doorbell ring or a detection starts
      * warm instead of paying a cold open.
      *
-     * Four gates. `autoRealtime: false` means the SDK opens nothing on its own initiative at all;
+     * Five gates. `autoRealtime: false` means the SDK opens nothing on its own initiative at all;
      * {@link EufyMegaOptions.prewarmEvents} must name the event, and it names none by default, which is
-     * what makes pre-warm opt-in; the station must be one the account actually reports; and its power tier
-     * must be one {@link EufyMegaOptions.prewarmTiers} allows.
+     * what makes pre-warm opt-in; the station must be one the account actually reports; it must not be a
+     * HomeBase S1 Pro (T9000), which answers no P2P lookup and is driven over RTC; and its power tier must
+     * be one {@link EufyMegaOptions.prewarmTiers} allows.
      *
      * The tier is resolved for the STATION whose session would open, which is why an attached camera is
      * judged by its base — {@link P2PCommandRouter.stationKeyOf} is the single source of that mapping, and
@@ -810,11 +856,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
@@ -835,19 +890,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;
     /**
@@ -959,6 +1040,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

@@ -202,9 +202,11 @@ export interface EufyMegaOptions extends MegaClientConfig {
  * that choice on every host. The SDK reports when the device last spoke; the caller decides what that
  * means — the same split as the snapshot cache TTL and the live power budget.
  *
- * P2P session state is **not** a liveness signal and is not carried here: sessions are opened only
- * when something needs one and closed when idle, so "no session" is the resting state of a healthy
- * device. Transport visibility lives on `getP2pSessions()` and the `p2pConnect`/`p2pClose` events,
+ * The absence of a P2P session is **not** a liveness signal and is not carried here: sessions are opened
+ * only when something needs one and closed when idle, so "no session" is the resting state of a healthy
+ * device. A station answering an open session is the opposite fact, positive evidence, and does advance
+ * the station's own {@link DeviceState.lastSeenMs} — never that of a device it covers, whose liveness its answer does
+ * not show. Transport visibility lives on `getP2pSessions()` and the `p2pConnect`/`p2pClose` events,
  * station-scoped like the session itself.
  *
  * The cloud record carries no connectivity field either: it has no `status` / `device_online`, and the
@@ -215,8 +217,9 @@ export interface DeviceState {
     /** The parent station whose P2P session covers this device (itself, when standalone). */
     stationSn: string;
     /**
-     * When the device last reported to the cloud, in ms. Bounded by
-     * the cloud's own slow refresh — minutes, not seconds — so it answers "is this device alive at all",
+     * When the device was last heard from, in ms: its last report to the cloud, or a later one over a
+     * realtime wire, a station's heartbeat answer on its open P2P session included. The cloud half is bounded
+     * by the cloud's own slow refresh — minutes, not seconds — so it answers "is this device alive at all",
      * not "what is it doing right now".
      */
     lastSeenMs?: number;
@@ -240,9 +243,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;
 }
@@ -332,7 +335,7 @@ export type EufyMegaEventMap = {
         map: VacuumMapSnapshot;
     }];
     /**
-     * A device reported to the cloud since the last poll — its {@link DeviceState.lastSeenMs} advanced.
+     * A device was heard from since the last poll — its {@link DeviceState.lastSeenMs} advanced.
      * Carries {@link DeviceState}; the host applies its own staleness threshold.
      *
      * Transport/session lifecycle is NOT this event: that's `p2pConnect`/`p2pClose`, station-scoped where

package/dist/core/contracts.d.ts

@@ -344,6 +344,8 @@ export type Command = {
     cmd: number;
     value: number;
     channel: number;
+    /** `"auto"`: the seal follows the session, level-2 with a key and level-1 without. Absent, level-2 only. */
+    form?: Extract<ScalarForm, "auto">;
 }
 /** P2P int-plus-string frame; the transport injects the authenticated account id string. */
  | {
@@ -852,7 +854,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);

package/dist/core/types.d.ts

@@ -80,8 +80,10 @@ export interface EufyDevice {
      */
     paramUpdatedAt?: Record<number, number>;
     /**
-     * The most recent {@link paramUpdatedAt} across all of this device's params, in **milliseconds**
-     * (comparable to `Date.now()` directly). `undefined` when the record carried no timestamp at all.
+     * When the device was last heard from, in **milliseconds** (comparable to `Date.now()` directly): the
+     * most recent {@link paramUpdatedAt} across all of its params, or a later report over a realtime wire,
+     * including a station answering its own P2P session's heartbeat. Never moves backwards. `undefined` when
+     * neither has been seen.
      *
      * This is an observation — "the device last reported at T" — deliberately **not** a reachability
      * verdict. How long a silence means "unreachable" depends on the device (a mains camera heartbeats