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

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

@@ -16,7 +16,10 @@ export interface DeviceRecord {
     deviceType?: number;
     model?: string;
     category?: string;
-    /** The app-shown device name (`device_name`); see {@link CloudRecord.name}. */
+    /**
+     * The app-shown device name: `alias_name` first on a vacuum, `device_name` first otherwise;
+     * see {@link CloudRecord.name}.
+     */
     name?: string;
     /** Parent HomeBase serial when attached (topology signal; see {@link CloudRecord.parentSn}). */
     parentSn?: string;
@@ -92,6 +95,8 @@ export declare class DeviceRegistry {
     private overlayRefusalReported;
     /** Per-serial capability cache for {@link capabilitiesForDevice}; `null` = negative hit. */
     private readonly deviceCapsCache;
+    /** Per-serial cloud data points of an AIoT robot, joined beneath the params in {@link record} — see {@link loadCloudDps}. */
+    private readonly cloudDps;
     /** Per-serial realtime state, keyed by param id in the device's own namespace (see {@link DeviceRecord.dpParams}). */
     private readonly dpParams;
     /** Callers blocked in {@link awaitRealtimeState}, released by the device's first report. */
@@ -181,9 +186,26 @@ export declare class DeviceRegistry {
      * transport stacks own the claim predicate over the record.
      */
     require(sn: string): EufyDevice;
+    /**
+     * Hold an AIoT robot's cloud data points: the cloud's last-known value of each one it has reported,
+     * from `getDeviceRelationList`'s per-device `dps`.
+     *
+     * The device list carries only some of a robot's data points, so a point the robot publishes on change
+     * alone (its scene list, its schedules, its consumables) has no value until it next reports. The
+     * relation list holds every one, for an account the robot is shared with as well as its owner.
+     *
+     * Kept apart from the device list's params rather than merged into them: those are what a poll diffs,
+     * and a diff retires the realtime report for that id, so a cloud value lagging the robot's last report
+     * would replace it. {@link record} joins this beneath both halves. A failure keeps what was held.
+     *
+     * Limited to {@link CLOUD_DPS_MODELS}, the models whose relation-list `dps` are checked to carry the
+     * DP numbers their realtime reports use.
+     */
+    private loadCloudDps;
     /**
      * Resolve a serial to a {@link DeviceRecord} with current params: starts from the device-list params, then
-     * overlays a fresh `get_device_param_list` when that call is available to this account.
+     * overlays a fresh `get_device_param_list` when that call is available to this account. An AIoT robot's
+     * cloud data points ({@link loadCloudDps}) sit beneath both, filling only ids neither carries.
      *
      * The overlay is **owner-gated** — a shared or member account is refused it for every device, permanently,
      * which {@link OWNER_ONLY_CODE} identifies — so when it is unavailable the device list is the source

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

@@ -98,6 +98,8 @@ export declare class EufyMega extends EventEmitter {
     private readonly prewarmTiers;
     /** Transport-side owner of the P2P sessions + all wire senders. */
     private readonly p2p;
+    /** Transport-side owner of the T9000 station sessions (sibling of {@link p2p}). */
+    private readonly rtc;
     /** Transport-side owner of the secure-MQTT ff09 lock/garage command path (sibling of {@link p2p}). */
     private readonly mqtt;
     /** Transport-side owner of the legacy Tuya REST command path for non-AIoT vacuums (G-series). */
@@ -234,6 +236,11 @@ export declare class EufyMega extends EventEmitter {
      *
      * The evidence set is widened, never replaced: the ids come back through the cloud record, and a
      * record that omits a realtime-only id would otherwise un-know it and re-trigger on the next report.
+     *
+     * The device is re-resolved against the fresh record before binding. A property gated on a
+     * realtime-only param enters the schema only once that param is evidence, and the value that made it
+     * evidence was stored before the property existed, so the record's realtime params are applied again
+     * to land it under the property's name.
      */
     private rebindReads;
     /** The distinct credential scopes the current MQTT roster needs — no devices on a scope, no connection. */
@@ -261,6 +268,8 @@ export declare class EufyMega extends EventEmitter {
      * only "differs from what was read before", which state already on hand can satisfy spuriously — and the
      * caller that has no expectation is the push path, where the signal itself is the news that a re-read is owed.
      *
+     * Only a write's observation throws at the deadline; a push with nothing moved answers `false`.
+     *
      * The cloud half is asked for through {@link DeviceRegistry.refreshedList}, never by fetching the account
      * list outright. The fetch is account-wide — one house list plus one device list per house — so a param that
      * never converges would otherwise spend a whole burst of those every iteration of this loop, and concurrent
@@ -409,8 +418,9 @@ export declare class EufyMega extends EventEmitter {
      * The `eufy_life` DP writes (smart lights) are secure-MQTT-only. `aiot-dp` routes to either the
      * Anker AIoT MQTT stack or the legacy Tuya REST router depending on the device's category
      * (`eufy_home_tuya` → Tuya, everything else → MQTT). The capability layer emits a single `aiot-dp`
-     * kind and stays transport-agnostic; only the facade sees both sides and decides here. Everything
-     * else is P2P.
+     * kind and stays transport-agnostic; only the facade sees both sides and decides here. A T9000
+     * station and the devices attached to it go over RTC, with an attached device's command refused
+     * unless its channel resolves back to it on the station. Everything else is P2P.
      */
     private routeCommand;
     /**
@@ -835,11 +845,14 @@ export declare class EufyMega extends EventEmitter {
      */
     setProperty(sn: string, name: string, value: boolean | number | string): Promise<void>;
     /**
-     * Restart a HomeBase.
+     * Restart a station: a HomeBase, or a camera-family device that is its own station.
      *
-     * **HomeBases only** — restart is a hub operation, so a non-HomeBase serial (a camera, an NVR)
-     * throws rather than doing nothing. The hub drops its connection and returns after a minute or two,
-     * so everything behind it is briefly offline. Verified on real hardware.
+     * The restart is `RESTART_HUB` on the station's broadcast channel, so it reaches whatever owns the
+     * P2P session. A standalone camera or doorbell owns its own session and is the station it restarts.
+     * A camera attached to a HomeBase is not — the same frame would restart its HomeBase — so its serial
+     * throws, as does any non-camera serial, rather than doing nothing. The device drops its connection
+     * and returns after a minute or two; a HomeBase takes everything behind it offline meanwhile.
+     * Verified on real hardware against a HomeBase and a standalone indoor camera.
      */
     reboot(sn: string): Promise<void>;
     /**
@@ -857,6 +870,7 @@ export declare class EufyMega extends EventEmitter {
      * exactly the reads it has.
      */
     private fetchDpCatalog;
+    /** The {@link CommandContext} for a device, built from `known` when that record is already in hand. */
     private commandContext;
     /**
      * **Generic P2P request/reply query** — sends a `SET_PAYLOAD` sub-command and resolves with the

package/dist/client/types.d.ts

@@ -390,7 +390,7 @@ export type EufyMegaEventMap = {
             sn: string;
             property: string;
             param: number;
-            expected?: boolean | number | string;
+            expected: boolean | number | string;
             observed?: boolean | number | string;
             timeoutMs: number;
         }

package/dist/core/contracts.d.ts

@@ -230,7 +230,7 @@ export interface StateConvergenceFailure {
     property: string;
     param: number;
     /** The RAW param value the write asked the device to report. */
-    expected?: boolean | number | string;
+    expected: boolean | number | string;
     /** What the param actually read when the deadline passed, absent where the device reported none at all. */
     observed?: boolean | number | string;
     timeoutMs: number;
@@ -248,7 +248,7 @@ export declare class StateConvergenceError extends Error {
     readonly sn: string;
     readonly property: string;
     readonly param: number;
-    readonly expected?: boolean | number | string;
+    readonly expected: boolean | number | string;
     readonly observed?: boolean | number | string;
     readonly timeoutMs: number;
     constructor(failure: StateConvergenceFailure);
@@ -548,19 +548,30 @@ export interface LiveVideoConfig {
  * 7 → `mp4a.40.39`); it fails the stream on anything else.
  */
 export type AudioCodec = "aac-lc" | "aac-eld" | "g711a";
+/** The codec a camera's speaker plays: `aac-eld` on a camera whose speaker plays it, `aac-lc` otherwise. */
+export type TalkbackCodec = Extract<AudioCodec, "aac-lc" | "aac-eld">;
 /**
  * One audio access unit, carrying the codec the station declared for it.
  *
- * Sample rate and channel count are deliberately absent: they are not on the wire. The v6 app assumes
- * 16 kHz mono for every audio type rather than reading them, so the SDK does not invent fields the
- * device never sent.
+ * Sample rate and channel count are absent for `aac-lc` and `g711a`: they are not on the wire, and the v6 app
+ * assumes 16 kHz mono for every audio type rather than reading them. An `aac-lc` frame is one ADTS frame and
+ * `g711a` is raw A-law. An `aac-eld` frame is one raw access unit with no transport framing, so it carries the
+ * AudioSpecificConfig that decodes it.
  */
-export interface LiveAudioFrame {
+export type LiveAudioFrame = {
     /** Codec declared in the frame header. */
-    codec: AudioCodec;
-    /** Elementary-stream bytes (ADTS-framed for the two AAC profiles). */
+    codec: "aac-lc" | "g711a";
+    /** One ADTS frame for `aac-lc`, raw A-law samples for `g711a`. */
     data: Buffer;
-}
+    config?: undefined;
+} | {
+    /** Codec declared in the frame header. */
+    codec: "aac-eld";
+    /** One raw AAC-ELD access unit. */
+    data: Buffer;
+    /** AudioSpecificConfig (ISO/IEC 14496-3) that decodes `data`. */
+    config: Buffer;
+};
 /**
  * One fragmented-MP4 (CMAF) output unit from the native muxer. `init` (the `ftyp`+`moov` init
  * segment) is present exactly once, on the first fragment; every fragment carries a `moof`+`mdat`
@@ -868,10 +879,11 @@ export interface MediaProvider {
     }): Promise<Record<string, unknown>>;
 }
 /**
- * An encoder that turns raw PCM into AAC-LC frames, supplied by the CALLER. The SDK ships none: the
- * device's audio path is fixed at AAC-LC 16 kHz mono, and every plausible encoder is either a native
+ * An encoder that turns raw PCM into AAC-LC frames, supplied by the CALLER. The SDK ships none: an
+ * `aac-lc` speaker plays AAC-LC 16 kHz mono, and every plausible encoder is either a native
  * dependency or an external process, both of which belong to the host rather than to a protocol SDK.
- * It is unnecessary where the audio is already AAC — see {@link TalkbackHandle}.
+ * It is unnecessary where the audio is already AAC — see {@link TalkbackHandle}. A camera whose speaker
+ * plays `aac-eld` refuses an encoder: a talkback opened with one is rejected before the speaker path opens.
  *
  * `encode` receives 16-bit little-endian mono PCM at 16 kHz and returns whole ADTS frames, zero or
  * more per call (an encoder buffers until it has a full 1024-sample block). `flush` drains a partial
@@ -886,17 +898,19 @@ export interface AacEncoder {
  * A live talkback session: audio pushed from the host to a camera's speaker, the mirror of
  * {@link LiveStreamHandle}'s inbound feed.
  *
- * Audio must be **AAC-LC, 16 kHz, mono, in ADTS frames** — what the device's path is fixed at, so a
- * stream at another rate or channel count is rejected rather than resampled (it would otherwise play
- * at the wrong pitch and speed). Feed it either way:
+ * Audio must be in the codec the camera's speaker plays, {@link TalkbackHandle.codec}:
  *
- *  - **ADTS AAC** — the default. Chunk boundaries are irrelevant; frames are recovered from the
- *    stream, so piping an encoder's output straight in works.
- *  - **PCM** — only when the handle was opened with an {@link AacEncoder}, which then does the
- *    conversion. `write` takes 16-bit little-endian mono PCM at 16 kHz instead.
+ *  - **`aac-lc`:** AAC-LC, 16 kHz, mono, in ADTS frames, through `write` / `writable()`. Chunk boundaries are
+ *    irrelevant; frames are recovered from the stream. With an {@link AacEncoder}, `write` takes 16-bit
+ *    little-endian mono PCM at 16 kHz instead.
+ *  - **`aac-eld`:** one raw AAC-ELD access unit with LD-SBR (16 kHz, mono, 512 samples) per `write`, or per
+ *    object-mode `writable()` write. No encoder applies.
  *
- * Frames are **paced** at their own playback rate (64 ms each) rather than flushed as fast as they
- * arrive, so feeding a file plays it at speed instead of overrunning the device. A live source keeps
+ * An `aac-lc` stream at another rate or channel count is rejected rather than resampled. An `aac-eld` unit longer
+ * than the device accepts is refused with an `error`.
+ *
+ * Frames are **paced** at their own playback rate (64 ms for `aac-lc`, 32 ms for `aac-eld`) rather than flushed as
+ * fast as they arrive, so feeding a file plays it at speed instead of overrunning the device. A live source keeps
  * the queue near-empty and is unaffected.
  *
  * @example
@@ -908,7 +922,16 @@ export interface AacEncoder {
  * ```
  */
 export interface TalkbackHandle {
-    /** Queue audio — ADTS frames, or PCM when an encoder was supplied. Partial frames are held. */
+    /**
+     * The codec this camera's speaker plays: `aac-eld` on a camera whose speaker plays it and whose stream on the same
+     * media session carries `aac-eld`, `aac-lc` otherwise, including when that stream carries no audio. It decides
+     * what {@link write} and {@link writable} take.
+     */
+    readonly codec: TalkbackCodec;
+    /**
+     * Queue audio: ADTS frames or PCM for `aac-lc`, one access unit per call for `aac-eld`. Partial ADTS frames are
+     * held.
+     */
     write(chunk: Buffer): void;
     /**
      * A `node:stream` Writable over {@link write}, for piping a file or an encoder's stdout. Applies
@@ -931,7 +954,7 @@ export interface TalkbackHandle {
      *
      * This deliberately does NOT fire on a merely-empty queue. A realtime source keeps the queue near
      * empty by design, so "queue is empty" arrives after the very first frame and stopping on it would
-     * cut the clip to 64 ms. {@link pending} is the instantaneous depth.
+     * cut the clip to one frame. {@link pending} is the instantaneous depth.
      */
     on(event: "finished", listener: () => void): this;
     /**

package/dist/core/store.d.ts

@@ -16,6 +16,8 @@ export interface PersistedSession {
     authToken: string;
     geoKey?: string;
     region: RegionShard;
+    /** The host `estimate_domain` answered; it names shards the region classification cannot (`ie`). */
+    estimatedDomain?: string;
     openudid: string;
     /** This install's reported device model + media user-agent, generated once and reused. */
     phoneModel?: string;