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

package/dist/transport/http/mega-client.d.ts

@@ -1,6 +1,7 @@
 import { type SessionEntry } from "../../core/crypto.js";
 import { type SessionStore } from "../../core/store.js";
 import { type Logger } from "../../core/logger.js";
+import type { EufyDevice } from "../../core/types.js";
 import type { SecureMqttCredentials } from "../mqtt/secure-mqtt.js";
 export type RegionShard = "eu-pr" | "us-pr";
 /**
@@ -354,11 +355,11 @@ export declare class MegaHttpClient {
     /** Authed call to a mega service host: app-{service}-{region}.eufy.com. */
     post<T = unknown>(service: string, path: string, body?: unknown, headerOverrides?: Record<string, string>): Promise<T>;
     /**
-     * Fetch the per-station DSK key used in the P2P cloud-lookup payload. Mirrors
+     * Fetch the per-station DSK key using each station's reported cloud category. Mirrors
      * the legacy `get_dsk_keys` body shape on the mega devicerelation service.
      * The P2P *local* lookup path does not need this; only the cloud path does.
      */
-    getDskKeys(stationSns: string[], priorDsks?: Record<string, string>): Promise<Record<string, {
+    getDskKeys(stations: ReadonlyArray<Pick<EufyDevice, "sn" | "category">>, priorDsks?: Record<string, string>): Promise<Record<string, {
         dskKey: string;
         expiration: number;
     }>>;

package/dist/transport/p2p/codec.d.ts

@@ -224,8 +224,8 @@ export declare function buildRawCommandPayload(data: Buffer, channel?: number, s
 export declare function buildAckPayload(dataTypeHeader: Buffer, seqNo: number): Buffer;
 /** Parse the 16-byte data-frame header that follows the "XZYH" magic. */
 export declare function parseDataFrameHeader(frame: Buffer): P2PDataFrameHeader;
-/** Parse a LOOKUP_ADDR or RLY_TO message's leading address record. */
-export declare function parseLookupAddr(msg: Buffer): Address;
+/** A LOOKUP_ADDR message's leading address record, or `undefined` for a message too short to carry it. */
+export declare function parseLookupAddr(msg: Buffer): Address | undefined;
 /** The relay servers a LIST_REQ_ACK names, in the order listed, without the unspecified address; records past the message's end are dropped. */
 export declare function parseRelayList(msg: Buffer): Address[];
 /** A RLY_PORT_ACK's mark and relay port, or `undefined` for a message too short to carry them. */

package/dist/transport/p2p/command-router.d.ts

@@ -102,6 +102,18 @@ export declare class P2PCommandRouter {
      * {@link liveSources} is a claim in flight.
      */
     private readonly liveSessionKeys;
+    /**
+     * The live source build in flight per `${parentSn}:${channel}`, settled once its connection is opened
+     * or refused.
+     *
+     * A build awaits its media session before it can file the source in {@link liveSources}, so a second
+     * request for the same camera in that window finds nothing cached. Building a second source there
+     * overwrites the first, and the orphan's teardown then closes the connection the cached one streams
+     * on. A request that finds a build here waits for it, until its own signal aborts, then resolves its
+     * session again and reuses what the build filed, or builds its own when that build failed. The entry
+     * is removed when the build settles and its promise never rejects, so each wait ends on a later state.
+     */
+    private readonly liveSourceBuilds;
     /**
      * The open talkback per `${parentSn}:${channel}`, if any. The device plays one audio stream at a
      * time and the session carries one audio sequence, so this path is exclusive where a live pull is
@@ -220,6 +232,11 @@ export declare class P2PCommandRouter {
      * so a start issued before the key arrives is dropped as `media-command-unsent`, and the stream then
      * shows nothing until a later keepalive tick happens to find the key. A connected session that cannot
      * carry the start is not a connected session, so this refuses rather than returning one.
+     *
+     * A session refused its key within the grace, or never connected, is closed and dropped from the manager at
+     * once. Nothing else releases it: no source holds it, a wired station's session never idles out, and the
+     * manager hands the same session to every later open of the camera, so the next open dials a fresh
+     * connection instead. A session another open has since replaced is left to its own close.
      */
     private openMediaSession;
     /**

package/dist/transport/p2p/database-wire.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Database wire — the ids and the whole-table query a station's on-station table and stored-image
+ * reads are built from.
+ *
+ * A HomeBase answers them over its P2P session and a T9000 over its portal control channel, with the
+ * same inner payloads, so both transports build their reads from this one module. The barrel does not
+ * re-export it: these are wire ids, not part of the package surface.
+ *
+ * @module p2p/database-wire
+ */
+/** CMD_DATABASE_IMAGE (1308) — fetch one stored image by its on-station path. */
+export declare const CMD_DATABASE_IMAGE = 1308;
+/** CMD_DATABASE (1306) — query one on-station table; reply carries `{cmd:10000,count,data:[…]}`. */
+export declare const CMD_DATABASE = 1306;
+/**
+ * Inner query cmds carried in a {@link CMD_DATABASE} payload. `FULL_TABLE` reads one table whole;
+ * `COMBINATION_WITH_AI` is the AI event-history read that bundles the face roster.
+ */
+export declare const DB_QUERY: {
+    readonly FULL_TABLE: 10000;
+    readonly COMBINATION_WITH_AI: 10011;
+    readonly QUERY_LOCAL: 10017;
+};
+/** How long a station's database reply has to arrive whole, when the caller states no bound. */
+export declare const DB_TABLE_TIMEOUT_MS = 15000;
+/**
+ * The query params the vendor app sends with a whole-table `CMD_DATABASE` read (inner `cmd 10000`).
+ * `count` bounds the row count.
+ */
+export declare function fullTableQuery(count?: number): Record<string, unknown>;

package/dist/transport/p2p/live-trace.d.ts

@@ -137,10 +137,10 @@ export type LiveTrace =
  *
  * Every ending of a level-2 wait carries one of these reasons, so a start refused for want of a key is
  * accounted for however it ended. `grace-elapsed` is a wait that ran out and states how long was waited;
- * the rest are answered without waiting, because the negotiation is one-shot per connection and a
- * concluded one is final. `no-cipher-key` and `derivation-failed` are about this account's cipher
- * material, `not-negotiating` and `session-closed` about the station or its connection — and only a
- * reason reached under a negotiation has a cipher to name.
+ * the rest are answered without waiting, because a concluded negotiation stays concluded until a
+ * re-prompt for `CMD_GATEWAYINFO` re-opens it. `no-cipher-key` and `derivation-failed` are about this
+ * account's cipher material, `not-negotiating` and `session-closed` about the station or its connection —
+ * and only a reason reached under a negotiation has a cipher to name.
  *
  * A `grace-elapsed` start proceeds at level 1 where it has such a form, and not at all where it does not.
  */

package/dist/transport/p2p/p2p-session.d.ts

@@ -180,11 +180,14 @@ export declare class P2PSession extends EventEmitter {
     private level2Seq;
     private rsaPrivateKey?;
     private rsaModulusHex?;
-    /** Guards the one-shot level-2 key negotiation kicked off by the GATEWAYINFO reply. */
+    /**
+     * Whether a level-2 key negotiation kicked off by a GATEWAYINFO reply is in flight. Cleared when it
+     * settles, so a later reply — the answer to {@link repromptLevel2Key} — negotiates again.
+     */
     private level2Negotiating;
     /**
      * Whether waiting for a level-2 key can still change the answer: `false` once one has been negotiated,
-     * once the one-shot negotiation concluded without one, and from the start when nothing can negotiate one.
+     * once a negotiation concluded without one, and from the start when nothing can negotiate one.
      */
     private level2Pending;
     /** Waiters parked in {@link awaitLevel2Key}, woken the moment the negotiation settles either way. */
@@ -260,7 +263,8 @@ export declare class P2PSession extends EventEmitter {
      * The session grace runs from connect, when the station is prompted for `CMD_GATEWAYINFO`. A negotiation
      * beginning later does not restart it: best-effort media can proceed without the key, and restarting
      * would charge another grace to a source that may already be streaming. A session whose negotiation has
-     * settled answers without waiting at all, since being one-shot is what makes that answer final.
+     * settled answers without waiting at all: the answer stands until {@link repromptLevel2Key} re-opens the
+     * wait, since the station is prompted for `CMD_GATEWAYINFO` only on connect and on that re-prompt.
      *
      * An own-session camera whose grace expires here is NOT thereby a camera that will fail to stream. Measured
      * on one account: own-session cameras of two device types negotiated a key, three others never did, and
@@ -276,12 +280,13 @@ export declare class P2PSession extends EventEmitter {
     /**
      * Ask the station for its gateway info a second time, re-opening a negotiation that concluded without a key.
      *
-     * The negotiation is one-shot per connection: the station is prompted once on connect, and a reply that
-     * never lands settles the wait so {@link awaitLevel2Key} answers `false` at once forever after. That is the
+     * Without this the station is prompted once on connect, and a negotiation that settles without a key
+     * leaves {@link awaitLevel2Key} answering `false` at once for the rest of that connection. That is the
      * right answer for best-effort media, which proceeds at level-1 — but an operation whose ONLY wire is
      * level-2 is then refused for the whole life of that connection, while a fresh session over the same
      * device negotiates a key normally. Measured: a session that had settled refused every such operation
-     * until it was rebuilt, at which point the station answered with a cipher id straight away.
+     * until it was rebuilt, at which point the station answered with a cipher id straight away. The reply to
+     * this ask runs the negotiation again and settles the re-opened wait either way.
      *
      * Bounded to one extra ask per connection, so a burst of such operations cannot turn a silent station into a
      * flood, and answers whether it asked — `false` when a key is already held, when nothing can negotiate one,
@@ -296,13 +301,14 @@ export declare class P2PSession extends EventEmitter {
      * `cipher_id`, resolve that cipher's private keys once (cloud `get_ciphers`, via the configured
      * `resolveCipherKey`), run the ECIES unwrap with the ECC key, and `setLevel2Key()`. A cipher with no
      * ECC key uses its RSA key instead and holds the RSA-decrypted 16-byte key as the AES-128-ECB level-2
-     * key. One-shot; emits `level2Ready` only when the AES-256-GCM key is negotiated, traces
+     * key. Emits `level2Ready` only when the AES-256-GCM key is negotiated, traces
      * `level2-set-payload-only` instead for the AES-128-ECB key, and emits `error` when the ECC unwrap
      * fails; an RSA unwrap failure is only traced (non-fatal either way — level-1 traffic keeps working).
      *
-     * Every outcome settles the wait in {@link awaitLevel2Key}, because being one-shot is what makes a
-     * failure final for this connection generation: nothing will retry it there, so a later command must be
-     * told at once rather than left to time out against a key that is not coming.
+     * Every outcome settles the wait in {@link awaitLevel2Key}, so a later command is told at once rather than
+     * left to time out against a key that is not coming. Settling also re-opens the negotiation, so a later
+     * GATEWAYINFO reply in the same connection generation runs it again; a lookup that completes after its
+     * generation ended settles nothing.
      */
     private negotiateLevel2Key;
     /**
@@ -682,11 +688,6 @@ export declare class P2PSession extends EventEmitter {
      * and holds no level-2 key.
      */
     private databasePayload;
-    /**
-     * Standard "give me the whole table" query params the eufy app uses for a direct
-     * `CMD_DATABASE` read (inner `cmd 10000`). `count` bounds the row count.
-     */
-    private fullTableQuery;
     /**
      * Request the on-device edge-AI **face roster** over P2P — the phone-free path.
      *
@@ -797,6 +798,8 @@ export declare class P2PSession extends EventEmitter {
      *
      * Only once the data type's reorder wait passes, or {@link REORDER_MAX_DATAGRAMS} pile up, is the datagram
      * treated as lost: a pending frame is discarded and delivery resumes from the earliest held datagram.
+     *
+     * A datagram shorter than the 8-byte DATA header carries no sequence number and is dropped unacknowledged.
      */
     private onData;
     /** Hold a datagram that arrived past a hole, and arm the wait for the missing one to be repeated. */
@@ -830,6 +833,13 @@ export declare class P2PSession extends EventEmitter {
      */
     private resetInboundSequencing;
     private ackTypeHeader;
+    /**
+     * Decrypt and dispatch one inbound data frame.
+     *
+     * A `CMD_GATEWAYINFO` (1100) reply carries the ECIES envelope for the level-2 session key. When a
+     * cipher-key resolver is configured, no key that seals a set-payload is held and no negotiation is in
+     * flight, the reply starts one (async, fire-and-forget); a reply landing while one is in flight is ignored.
+     */
     private handleFrame;
     private send;
     /** Finish the END send on the current socket before closing it; send completion is not a peer ACK. */

package/dist/transport/p2p/readable-egress.d.ts

@@ -25,6 +25,8 @@ export interface ReadableEgressOptions {
 /**
  * Wrap a shared-source {@link Consumer} in a fresh Readable. The consumer is detached when the
  * Readable is destroyed/ended, so callers own the lifetime by owning the stream.
- * Frames arrive through onMedia, preserving their source-arrival metadata.
+ * Frames arrive through onMedia, preserving their source-arrival metadata. The consumer's battery
+ * `budget` notice is re-emitted unchanged as a `budget` event carrying a {@link StreamBudgetNotice};
+ * without an `extend()` within its grace the shared source ends the consumer and the Readable reaches EOF.
  */
 export declare function openReadableFromConsumer(consumer: Consumer, opts?: ReadableEgressOptions): Readable;

package/dist/transport/p2p/shared-live-source.d.ts

@@ -256,7 +256,8 @@ export declare class SharedLiveSource {
      *
      * The previous stream is dropped rather than stopped through the state machine: it speaks to a session that
      * is gone, and its `stop` would be read as an upstream end. Only a warm-up that asked for a replacement
-     * rewarms, so this is inert on a source that is streaming or has already failed.
+     * rewarms, so this is inert on a source that is streaming or has already failed. Each call replaces the
+     * re-issue ticker rather than adding one, so the start goes out once per interval however often it runs.
      */
     rewarm(): void;
     /**

package/dist/transport/push/store.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Persistence for FCM credentials + seen persistent-ids, so we register the FCM
+ * token ONCE and just reconnect (and don't re-receive old pushes) across runs.
+ */
+import { FileSessionStore } from "../../core/store.js";
 import type { FcmCredentials } from "./types.js";
 export interface PersistedPush {
     creds: FcmCredentials;
@@ -14,10 +19,6 @@ export declare class MemoryFcmStore implements FcmStore {
     save(p: PersistedPush): void;
     clear(): void;
 }
-export declare class FileFcmStore implements FcmStore {
-    private readonly path;
-    constructor(path: string);
-    load(): PersistedPush | null;
-    save(p: PersistedPush): void;
-    clear(): void;
+/** JSON-file FCM store: the {@link FileSessionStore} file format and write guarantees, on the push record. */
+export declare class FileFcmStore extends FileSessionStore<PersistedPush> implements FcmStore {
 }

package/dist/transport/rtc/command-router.d.ts

@@ -14,6 +14,11 @@
  * a live pull holds it open. Sends on a session are serialised; an ACK is correlated by its outer command
  * and segment, since it carries no inner command. An ACK is not an observation of the resulting state.
  *
+ * The station's own database is read over the same channel: a `set-payload` with inner `1306`
+ * (CMD_DATABASE) answers a table and inner `1308` (CMD_DATABASE_IMAGE) a stored image, each as one
+ * notify frame carrying the whole document, zstd-compressed when large. The notify link carries
+ * unrelated station reports between them, so a reply is matched by its content, never by arrival order.
+ *
  * Live view of an attached camera rides the same session (the hub accepts one RTC session per account),
  * through one shared live source per station: the station serves one camera at a time, so a second
  * camera is refused until the first one's view ends.
@@ -72,8 +77,48 @@ export declare class RtcCommandRouter {
     private readonly lives;
     private readonly warm;
     private readonly callSources;
+    private lastTransaction;
     constructor(deps: RtcCommandRouterDeps);
     dispatchCommand(route: RtcRoute, cmd: Command): Promise<void>;
+    /**
+     * Query one on-station table over the station's control channel and answer its rows.
+     *
+     * Sends the `1350` envelope with inner `{cmd: 1306, payload: {cmd: 10000, table, payload, transaction}}`,
+     * the whole-table query, on the station channel. The hub ACKs on the command link and answers with one notify frame whose body
+     * carries `{cmd, table, data, mIntRet, msg, transaction, …}`, echoing the read's `transaction`; that echo
+     * is the only thing a reply is attributed by, and every read sends a `transaction` no other read on this
+     * router has sent. Resolves with the reply's `data` rows. Rejects with the hub's `msg` on a non-zero
+     * `mIntRet`, on an ACK refusing the envelope, at once when `signal` aborts (queued or sent), when the
+     * session closes, and when `timeoutMs` (default {@link DB_TABLE_TIMEOUT_MS}) elapses with no reply.
+     *
+     * One read or command at a time per station: the read holds the station's send queue until it settles.
+     */
+    readTable(route: RtcRoute, table: string, opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<unknown[]>;
+    /**
+     * Fetch one stored image by its on-station path over the station's control channel.
+     *
+     * Sends the `1350` envelope with inner `{cmd: 1308, payload: [{file}]}` on the station channel. The hub
+     * ACKs on the command link and answers with one notify frame whose body is `{file, content}`, `content`
+     * the image in base64, and no `transaction`; the reply is the one whose `file` equals `filePath`. A reply
+     * arriving after an abandoned read of the same path carries that path's bytes, which are the bytes a
+     * later read of it asks for. Resolves with the decoded bytes. Rejects on an ACK refusing the envelope,
+     * at once when `signal` aborts (queued or sent), when the session closes, and when `timeoutMs` (default
+     * {@link DB_TABLE_TIMEOUT_MS}) elapses with no reply.
+     *
+     * One read or command at a time per station: the read holds the station's send queue until it settles.
+     */
+    readImage(route: RtcRoute, filePath: string, opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<Buffer>;
+    /**
+     * A `transaction` stamp in the vendor app's shape, a decimal epoch-in-milliseconds string, strictly
+     * greater than the last one this router issued, so two reads in the same millisecond never share one.
+     */
+    private nextTransaction;
     /**
      * The media of a camera on a T9000: live video, a readable feed and a live still over the station's
      * session. Recording has no wire here and is refused; the optional members it has no wire for are absent.
@@ -108,9 +153,24 @@ export declare class RtcCommandRouter {
     private refuseIfWatched;
     private newLiveSource;
     /**
-     * Completes on the command ACK or a correlated control-result notification. The notification must
-     * match the request channel, parameter and segment and contain a structured payload. Receipt does
-     * not establish physical actuation. The command is sent once, bounded by {@link ACK_TIMEOUT_MS}.
+     * Send one envelope on the station's session, queued behind its other sends, and settle as
+     * {@link sendAwaitAck} does. `body` is the inner payload; the station session, the `account_id` it is
+     * stamped with and the packet are resolved here, so a command and a read reach the wire through the same
+     * steps. With `reply.signal`, the caller's wait rejects the moment it aborts, also while the send is still
+     * queued; a send not yet made by then is skipped.
+     */
+    private sendQueued;
+    /**
+     * Without `reply`, completes on the command ACK or a correlated control-result notification. The
+     * notification must match the request channel, parameter and segment and contain a structured payload.
+     * Receipt does not establish physical actuation. Bounded by {@link ACK_TIMEOUT_MS}.
+     *
+     * With `reply`, a zero-result ACK is not the answer: the first notify body (an object) for which
+     * `reply.pick` answers a value resolves with it, one `pick` throws on rejects with that error, and every
+     * other notify frame is left alone. Bounded by `reply.timeoutMs` (default {@link DB_TABLE_TIMEOUT_MS}),
+     * and ended by `reply.signal`; one already aborted is not sent.
+     *
+     * Either way an ACK with a non-zero result code rejects, and the command is sent once.
      */
     private sendAwaitAck;
     private newSession;

package/dist/transport/rtc/portal-packet.d.ts

@@ -1,14 +1,3 @@
-/**
- * The command framing a HomeBase S1 Pro (T9000) speaks over its WebRTC data channel — the wire the
- * security.eufy.com web client builds, reproduced byte-exact.
- *
- * A packet is a 16-byte header behind the ASCII magic `XZYH`, then a JSON body, sent in the clear (the
- * DTLS channel is the encryption). Replies come back with `isResponse = 1`, the same `segment` the
- * request carried, and a body whose first four bytes are a little-endian result code.
- *
- * Every offset is the portal bundle's header builder and parser (`Gr()` / `Qr()`) and its
- * `worker_sctp_send`.
- */
 export declare const PORTAL_HEADER_LENGTH = 16;
 /** The SET_PAYLOAD envelope. */
 export declare const PORTAL_CMD_SET_PAYLOAD = 1350;
@@ -61,8 +50,9 @@ export declare function isPortalPacket(buf: Buffer): boolean;
 /** A complete request packet: header + body. */
 export declare function buildPortalPacket(req: PortalRequest): Buffer;
 /**
- * Parse an inbound packet. On the command channel the body opens with the int32 result code and may
- * carry JSON after it; on the notify channel the whole body is JSON with a nested `cmd`.
+ * Parse an inbound packet, opening a zstd-compressed one first. On the command channel the body opens
+ * with the int32 result code and may carry JSON after it; on the notify channel the whole body is JSON
+ * with a nested `cmd`. `undefined` for a frame that is neither a packet nor a stream holding one.
  */
 export declare function parsePortalPacket(buf: Buffer, linkType?: number): PortalResponse | undefined;
 /** A 1..255 segment counter that never yields 0 (the portal reserves it). */

package/dist/transport/stored-image-cache.d.ts

@@ -9,6 +9,12 @@ export declare class StoredImageCache {
     private readonly activeDevices;
     private activeDownloads;
     private generation;
+    /**
+     * Bumped by {@link clearLifecycleErrors}. A lifecycle failure from a download started under an older
+     * count is not recorded; the candidate is queued again, unless a newer one is already queued, so the
+     * current session fetches it.
+     */
+    private lifecycle;
     constructor(downloader: (url: string, deviceKey: string) => Promise<Buffer>, logger: Logger, clock?: () => number, isLifecycleError?: (error: unknown) => boolean);
     /**
      * Observe a normalized thumbnail URL and start acquisition eagerly.
@@ -20,6 +26,14 @@ export declare class StoredImageCache {
     observe(deviceKey: string, url: string): void;
     /** Return retained bytes without starting or awaiting network work. */
     snapshotStored(deviceKey: string): Promise<Buffer>;
+    /**
+     * Forget every device's recorded lifecycle failure, keeping retained bytes and candidate state.
+     *
+     * A lifecycle failure describes the session that was current when the download ran, so it no longer
+     * holds once a login succeeds again; {@link snapshotStored} then answers from the retained image, or
+     * with the reason a stored image is absent. A download in flight across the call cannot record one.
+     */
+    clearLifecycleErrors(): void;
     /** Invalidate all retained and candidate state. */
     clear(): void;
     private pump;

package/package.json

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