@mega-yfue/eufy-sdk 0.3.0-beta.0 → 0.3.0-beta.10

package/dist/model/capabilities/battery.d.ts

@@ -90,6 +90,11 @@ export type BatteryActions = Surface<typeof BATTERY_MEMBERS>;
  * The richer raw `APP_CMD_SET_POWER_SOURCE` blob is a separate param, surfaced as `powerSourceInfo`.
  */
 declare function decodePowerSource(raw: string | number | boolean): number | string;
+/**
+ * Power tier of a camera for its live-media budget and standalone P2P session: `"battery"` only when it
+ * resolved the `battery` capability AND is not a listed mains-only model, else `"wired"`.
+ */
+export declare function cameraPowerTier(model: string | undefined, capabilities: ReadonlySet<string>): "wired" | "battery";
 /**
  * The params whose subject IS the physical cell — so every member reading one must carry
  * {@link notMainsCamera}.

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

@@ -91,8 +91,9 @@ export declare class SessionExpiredError extends Error {
     /**
      * Whether this rejection landed inside that bar — a token replaced recently and rejected again since.
      *
-     * It says the session is being DISPLACED rather than expiring: something else is signing in on this
-     * account, and replacing the token again only trades one login for another.
+     * That is the shape displacement by another client signed in on this account has, where replacing the
+     * token again only trades one login for another. It is not proof of one, since a cloud refusing to
+     * re-issue the session looks the same.
      */
     readonly contended: boolean;
     constructor(message: string, opts?: {
@@ -212,6 +213,8 @@ export declare class MegaHttpClient {
     private sessionKey?;
     /** Per-host ECDH session keys for non-mega gateways (e.g. eufylife) keyed by host. */
     private readonly sessionKeys;
+    /** The in-flight key exchanges, by host and the token they carry — see {@link ensureSessionKey}. */
+    private readonly keyExchanges;
     /**
      * The held credential. `userId` is the login reply's `ap_cloud_user_id` where it has one — the Anker
      * Passport cloud's id — while `accountUserId` is the eufy account's own `user_id`.
@@ -318,6 +321,8 @@ export declare class MegaHttpClient {
      * so it MUST be reused (don't re-exchange after login).
      */
     ensureSessionKey(targetHost?: string): Promise<SessionEntry>;
+    /** One key exchange against `host`, installed as that host's key. */
+    private exchangeSessionKey;
     /**
      * Signed + encrypted POST. Content-type auto-falls-back (text/plain ↔ json).
      *
@@ -523,8 +528,8 @@ export declare class MegaHttpClient {
      * like the same device — and the cloud keeps one session per device. Each finds its token rejected, replaces
      * it, and evicts the other: an unbounded login war, silent, and repeated logins are exactly what makes an
      * account start demanding captchas. The first replacement is immediate, because a token displaced once is
-     * the ordinary case; a second one soon after is evidence of contention rather than expiry, so the wait grows
-     * and a caller is told the honest reason instead of being served a fight.
+     * the ordinary case; a second one soon after has the shape of contention rather than expiry, so the wait grows
+     * and a caller is told what was seen instead of being served a fight.
      */
     private recoveryDue;
     /**

package/dist/transport/mqtt/secure-mqtt.d.ts

@@ -79,15 +79,24 @@ export interface SecureMqttOptions {
 export declare class SecureMqtt extends EventEmitter implements RealtimeTransport {
     readonly kind: "smqtt";
     private client?;
+    /**
+     * The in-flight or established connect. A client ID is exclusive at the broker, so a second mqtt.js
+     * client under the same ID evicts the first, which reconnects and evicts it back, forever; `connect()`
+     * therefore hands a later caller this same attempt instead of opening a rival. Cleared when the
+     * attempt fails and on `disconnect()`, so a caller can still retry or deliberately reconnect.
+     */
+    private connecting?;
     private readonly o;
     private readonly logger;
     constructor(opts: SecureMqttOptions);
     get id(): string;
+    /** Connect, joining the attempt in `connecting` when one is already opening or open. */
+    connect(): Promise<void>;
     /**
      * Open the broker connection, resolving once it is established. Pinned to a broker instance's IP, or
      * to the plain hostname; only the former needs its own TLS shape, see `./bare-ip-tls.ts`.
      */
-    connect(): Promise<void>;
+    private open;
     /**
      * Subscribe every inbound leg this device's line uses (see `topics.ts` — one `/res` for most lines,
      * four topics for `eufy_life`).

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

@@ -128,13 +128,18 @@ export declare class P2PSession extends EventEmitter {
     private lookupTimer?;
     private heartbeatTimer?;
     private connectTimer?;
-    /** Our own bound host:port, self-reported inside LOOKUP_WITH_KEY requests (see sendLookups). */
-    private selfAddress?;
+    /** Extra sockets registered alongside {@link socket} while connecting; see {@link PUNCH_PROBE_SOCKETS}. */
+    private probeSockets;
+    /** Cloud lookup inputs resolved once for a connection. */
+    private cloudLookup?;
+    /** Local outbound IPv4 reported inside LOOKUP_WITH_KEY requests. */
+    private selfHost?;
     /** In-flight multi-datagram frame per data channel (see onData). */
     private readonly pendingByDataType;
-    /** Last datagram sequence number seen per dataType — used to detect a lost/reordered datagram
-     * mid-frame and drop the (now unrecoverable) partial frame instead of splicing wrong bytes. */
+    /** Last delivered datagram sequence number per data type. */
     private readonly lastSeqByType;
+    /** Held datagrams and their active gap timer, grouped by data type. */
+    private readonly reorderByType;
     private tracedDatagramGaps;
     private readonly level1Key;
     /** Negotiated 32-byte level-2/gateway key (AES-256-GCM). Set via setLevel2Key once known. */
@@ -296,6 +301,8 @@ export declare class P2PSession extends EventEmitter {
      */
     private static detectLocalIp;
     private sendLookups;
+    /** Register a bound socket's own port with each configured cloud lookup address. */
+    private sendCloudLookup;
     /**
      * Route one inbound UDP datagram by its message type, tracing every non-DATA one and any type this session
      * does not model.
@@ -309,6 +316,10 @@ export declare class P2PSession extends EventEmitter {
      */
     private onMessage;
     private beginCheckCam;
+    /** Bind additional UDP source ports before the first cloud lookup. */
+    private startPunchProbes;
+    /** Close all lookup sockets except the one that completed the handshake. */
+    private stopPunchProbes;
     private onConnected;
     /**
      * Start the realtime media stream for a camera `channel` (the device's `device_channel`; defaults to
@@ -601,8 +612,7 @@ export declare class P2PSession extends EventEmitter {
      * Acknowledge and reassemble one DATA datagram, sequenced independently per data type.
      *
      * The device numbers each data type's datagrams in its own 16-bit space and repeats what it thinks was
-     * lost, so a datagram that does not advance the sequence — a duplicate, or one already superseded — is a
-     * retransmission of something already reassembled: it is acknowledged, then ignored. Distance is measured
+     * lost. A repeat of something already delivered is acknowledged, then ignored. Distance is measured
      * modulo the sequence space and read as backwards beyond {@link SEQUENCE_LOOKBACK}, which is what lets the
      * numbering wrap without the next datagram looking like a jump of nearly a full space.
      *
@@ -612,11 +622,29 @@ export declare class P2PSession extends EventEmitter {
      * numbering and the half-assembled frame goes — because ignoring it would freeze the mark, and every
      * datagram of the new numbering would then be read as behind it too, for as long as it took to climb back.
      *
-     * Only a forward gap means a datagram is genuinely missing. A logical frame's payload spans datagrams that
-     * carry no header of their own, so the bytes cannot be reassembled around the hole: whatever was pending
-     * for that data type is discarded, and the frame is rebuilt from the next header.
+     * A forward gap means a datagram has not arrived YET, which is not the same as lost. The device repeats
+     * unacknowledged datagrams, so successors are held for a bounded wait and delivered strictly in sequence
+     * if the missing one arrives. A logical frame's payload spans datagrams that carry no header of their
+     * own, so reassembling around a hole is impossible; waiting for it is what keeps the frame whole.
+     *
+     * Only once {@link REORDER_WAIT_MS} 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.
      */
     private onData;
+    /** Hold a datagram that arrived past a hole, and arm the wait for the missing one to be repeated. */
+    private holdForRetransmit;
+    /** Start a full wait for the current hole, leaving an existing wait undisturbed. */
+    private armReorderTimer;
+    /** Deliver held datagrams that now follow directly on from the last one delivered. */
+    private drainReorder;
+    /**
+     * The missing datagram was not repeated in time: report the gap, drop the frame it belonged to, and
+     * resume from the earliest datagram still held so the stream keeps moving.
+     */
+    private abandonHole;
+    private clearReorderTimer;
+    /** Reassemble one in-sequence datagram body into logical frames. */
+    private reassemble;
     /**
      * Forget where each data type's sequence numbering had reached, and drop any half-reassembled frame.
      *

package/dist/transport/push/push-client.d.ts

@@ -10,6 +10,10 @@ import type { FcmCredentials, PushEvent, RawPushMessage } from "./types.js";
 import { type Logger } from "../../core/logger.js";
 /**
  * Normalises a decoded eufy envelope without consulting device semantics; semantic event names remain unset.
+ *
+ * The detail (`event_type`, `pic_url`, `cipher`) is read from the deepest level of
+ * `payloadLevels`; identity (`device_sn`, `station_sn`) is gathered from every level, deepest
+ * first, so a serial is found whichever level the push carries it on.
  * @internal
  */
 export declare function normalizePushEvent(raw: RawPushMessage): PushEvent;
@@ -55,6 +59,13 @@ export declare class PushClient extends EventEmitter {
      * {@link MAX_LOGIN_FAILURES} consecutive attempts (creds genuinely stale) is it emitted as `error`.
      */
     private onLoginError;
+    /**
+     * Decode one MCS `DataMessageStanza` into a {@link RawPushMessage} and the normalised event.
+     *
+     * `payload` carries the whole app_data envelope, with its `payload` entry (base64 of NUL-terminated
+     * JSON) parsed in place: the envelope's own keys, `device_sn` and `station_sn` among them, sit beside
+     * that entry.
+     */
     private handleDataMessage;
     private startHeartbeat;
     private stopHeartbeat;

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

@@ -1,11 +1,11 @@
 /**
  * eufy FCM push payload types.
  *
- * A push arrives as an MCS DataMessageStanza whose `app_data` has a `payload`
- * entry = base64( NUL-terminated JSON ). That JSON is the EufyPushMessage; its
- * nested `payload` is device-type specific. The v6 app enriches these with AI
- * detection fields (person/vehicle/pet/package/faces/crops/short video) — see
- * PushEnrichment.
+ * A push arrives as an MCS DataMessageStanza whose `app_data` entries make up the
+ * EufyPushMessage envelope. Its `payload` entry is base64( NUL-terminated JSON ), the
+ * device-type specific detail, which may itself nest a further `payload`. The v6 app
+ * enriches these with AI detection fields (person/vehicle/pet/package/faces/crops/short
+ * video) — see PushEnrichment.
  */
 /**
  * Raw MCS frame: a tag + the decoded protobuf object.
@@ -31,10 +31,10 @@ export interface RawPushMessage {
     persistentId?: string;
     ttl?: number;
     sent?: string;
-    /** The decoded eufy payload (the `payload` app_data entry, JSON-parsed). */
+    /** The eufy envelope, as `EufyPushMessage` describes it. */
     payload: EufyPushMessage;
 }
-/** The eufy JSON envelope inside the push. */
+/** The eufy envelope: the push's `app_data` entries, with the `payload` entry JSON-parsed in place. */
 export interface EufyPushMessage {
     type?: string | number;
     title?: string;
@@ -45,7 +45,7 @@ export interface EufyPushMessage {
     push_time?: string;
     doorbell?: string;
     "google.c.sender.id"?: string;
-    /** Device-type specific body (often a JSON string that we further parse). */
+    /** The decoded `payload` entry: device-type specific detail, which may nest a further `payload`. */
     payload?: PushPayload;
     [k: string]: unknown;
 }

package/package.json

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