@mega-yfue/eufy-sdk 0.2.0-beta.20 → 0.2.0-beta.21

package/dist/client/types.d.ts

@@ -5,7 +5,7 @@
  * `interface EufyMega` (the typed on/once/off/emit overloads) stays in `eufy-mega.ts` next to the
  * class — TS declaration merging requires both in the same module.
  */
-import type { MegaClientConfig } from "../transport/http/mega-client.js";
+import type { MegaClientConfig, SessionExpiredError } from "../transport/http/mega-client.js";
 import type { FcmStore } from "../transport/push/store.js";
 import type { FfmpegLevel } from "../transport/ffmpeg.js";
 import type { DeviceEventMap } from "../model/capabilities/index.js";
@@ -375,8 +375,12 @@ export type EufyMegaEventMap = {
      * token expired. The SDK has already cleared the persisted session, so recovery is a fresh `login()`
      * (which usually needs 2FA). Distinct from `error`: a session error is emitted ONLY here, not also
      * on `error`.
+     *
+     * The error carries the rate: `err.retryAfterMs` is how long the next session replacement is barred
+     * for, and `err.contended` says this session is being displaced by another client rather than expiring
+     * — which a re-login does not answer. A login made before that wait elapses extends it.
      */
-    sessionExpired: [err: Error];
+    sessionExpired: [err: SessionExpiredError];
     error: [err: Error];
 };
 /** Event names {@link EufyMega} can emit. */

package/dist/index.js

@@ -1092,9 +1092,25 @@ var MegaApiError = class extends Error {
 };
 var OWNER_ONLY_CODE = 20004;
 var SessionExpiredError = class extends Error {
-  constructor(message) {
+  /**
+   * How long the next session replacement is barred for, in milliseconds; `0` when nothing bars one now.
+   *
+   * The remainder of the client's own hold-off, which doubles per consecutive replacement and is capped —
+   * and which every replacement extends, whether the client spent it or a login made on this error did.
+   */
+  retryAfterMs;
+  /**
+   * 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.
+   */
+  contended;
+  constructor(message, opts = {}) {
     super(message);
     this.name = "SessionExpiredError";
+    this.retryAfterMs = opts.retryAfterMs ?? 0;
+    this.contended = opts.contended ?? false;
   }
 };
 var EufyCloudErrorCode = {
@@ -1133,7 +1149,7 @@ var LoginStatus = {
 var REAUTH_HOLD_OFF_MS = 6e4;
 var REAUTH_HOLD_OFF_CAP_MS = 30 * 6e4;
 var REAUTH_STABLE_MS = 10 * 6e4;
-var CONTENDED_SESSION_HINT = "another client may be signed in with the same account and device identity, and each login displaces the other's session; give each client its own openudid";
+var CONTENDED_SESSION_HINT = "another client signed in on this account keeps displacing this session \u2014 the cloud holds about one session per account and device identity, so each login ends the other's; where the other client is another SDK install, give each its own openudid";
 function tokenRejected(code, msg) {
   return code === EufyCloudErrorCode.SESSION_KICKED || /user_id is empty|invalid[^,]*\btoken\b|\btoken\b[^,]*(expired|error|not exist)|kicked|(?:\btoken\b|\bsession\b)[^,]*does not exist|unauthor/i.test(msg ?? "");
 }
@@ -1183,9 +1199,11 @@ var MegaHttpClient = class {
   loggingIn = false;
   /** The one in-flight re-login every call rejected on the same dead token waits on. */
   reauthAttempt;
-  /** Replacements since the held session last proved stable, and when the last one ran — see {@link recoveryDue}. */
+  /** Replacements since the held session last proved stable, and when the last one ran — see {@link holdOffRemainingMs}. */
   recoveries = 0;
   lastRecoveryAt = 0;
+  /** A token of ours has been rejected and not yet replaced — see {@link noteTokenReplacement}. */
+  rejectedTokenPending = false;
   constructor(cfg) {
     this.cfg = {
       appName: "eufy_mega",
@@ -1468,12 +1486,17 @@ var MegaHttpClient = class {
     const tokenFinished = identityError && retry.identity || authed && last?.status === 401 && tokenRejected(last.code, last.msg);
     if (tokenFinished) {
       const reason = `${path} failed (${last?.status}/${last?.code}): ${last?.msg}`;
+      this.rejectedTokenPending = true;
       const recovery = retry.reauth ? "unrecoverable" : await this.recoverRejectedSession(sentToken);
       if (recovery === "retry")
         return this.postSigned(host, path, body, authed, { ...retry, reauth: true }, headerOverrides);
       if (!this.sessionReplacedSince(sentToken))
         this.clearSession();
-      throw new SessionExpiredError(recovery === "held-off" ? `${reason} \u2014 ${CONTENDED_SESSION_HINT}` : reason);
+      const contended = recovery === "held-off";
+      throw new SessionExpiredError(contended ? `${reason} \u2014 ${CONTENDED_SESSION_HINT}` : reason, {
+        retryAfterMs: this.holdOffRemainingMs(),
+        contended
+      });
     }
     throw new MegaApiError(`${path} failed (${last?.status}/${last?.code}): ${last?.msg}`, last?.code, last?.status);
   }
@@ -1798,8 +1821,7 @@ var MegaHttpClient = class {
       return "unrecoverable";
     if (!this.recoveryDue())
       return "held-off";
-    this.recoveries++;
-    this.lastRecoveryAt = Date.now();
+    this.noteTokenReplacement();
     this.clearSession();
     return await this.reauthenticate() ? "retry" : "unrecoverable";
   }
@@ -1814,20 +1836,47 @@ var MegaHttpClient = class {
    * and a caller is told the honest reason instead of being served a fight.
    */
   recoveryDue() {
-    if (this.recoveries === 0)
+    const remaining = this.holdOffRemainingMs();
+    if (remaining === 0)
       return true;
-    const wait = Math.min(REAUTH_HOLD_OFF_MS * 2 ** (this.recoveries - 1), REAUTH_HOLD_OFF_CAP_MS);
-    const waited = Date.now() - this.lastRecoveryAt;
-    if (waited >= wait)
-      return true;
-    this.logger.warn(`[mega] token rejected ${Math.round(waited / 1e3)}s after the last replacement \u2014 holding off ${Math.round(wait / 1e3)}s. ${CONTENDED_SESSION_HINT}`);
+    this.logger.warn(`[mega] token rejected ${Math.round((Date.now() - this.lastRecoveryAt) / 1e3)}s after the last replacement \u2014 holding off ${Math.round(remaining / 1e3)}s more. ${CONTENDED_SESSION_HINT}`);
     return false;
   }
+  /**
+   * How much longer a token replacement must wait, in milliseconds; `0` when one may run now.
+   *
+   * The wait doubles per consecutive replacement and is capped, and it is what {@link recoveryDue} gates
+   * this client's own recovery on — and what {@link SessionExpiredError.retryAfterMs} hands a host that
+   * drives its own. One function so the two cannot disagree about the rate, which they would have to for
+   * a host to be told it may retry while this client is still holding off.
+   */
+  holdOffRemainingMs() {
+    if (this.recoveries === 0)
+      return 0;
+    const wait = Math.min(REAUTH_HOLD_OFF_MS * 2 ** (this.recoveries - 1), REAUTH_HOLD_OFF_CAP_MS);
+    return Math.max(0, wait - (Date.now() - this.lastRecoveryAt));
+  }
+  /**
+   * Count one token replacement against the hold-off, and clear the rejection it answered.
+   *
+   * Every replacement passes through here, wherever it was spent from: {@link recoverRejectedSession}, and
+   * a {@link login} that follows a rejection this client surfaced. A hold-off that counted only its own
+   * would be no bound at all — the wait would sit at its first value however many sessions had been spent,
+   * and {@link SessionExpiredError.retryAfterMs} would report a minute while logins ran every few seconds.
+   * Which of the two counted a given replacement is the flag: the recovery path clears it before logging
+   * in, so the login cannot count the same one again.
+   */
+  noteTokenReplacement() {
+    this.recoveries++;
+    this.lastRecoveryAt = Date.now();
+    this.rejectedTokenPending = false;
+  }
   /**
    * Note that the held session is working. A replacement that keeps serving calls for long enough is not
    * contention, so the hold-off is forgotten and the next genuine expiry recovers immediately.
    */
   noteSessionWorking() {
+    this.rejectedTokenPending = false;
     if (this.recoveries > 0 && Date.now() - this.lastRecoveryAt > REAUTH_STABLE_MS)
       this.recoveries = 0;
   }
@@ -1944,6 +1993,8 @@ var MegaHttpClient = class {
     this.sessionKey = void 0;
     await this.ensureSessionKey();
     this.persist();
+    if (this.rejectedTokenPending)
+      this.noteTokenReplacement();
     return { status: LoginStatus.Ok, session: { userId, authToken, geoKey: this.auth_.geoKey, raw: res } };
   }
   /** Save the current token + session key for reuse across runs. */