@mega-yfue/eufy-sdk 0.3.0-beta.3 → 0.3.0-beta.5

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/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.3",
+  "version": "0.3.0-beta.5",
   "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",