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

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. */
@@ -3179,7 +3230,14 @@ function describeBound(modules, bound, ctx) {
       else
         undescribedActions.push(name);
     }
-    out.push({ capability: m.capability, accessor, reads: reads2, actions, undescribedActions, events: emitsOf(m) });
+    out.push({
+      capability: m.capability,
+      accessor,
+      reads: reads2,
+      actions,
+      undescribedActions,
+      events: emitsOf(m, reads2, ctx)
+    });
   }
   return out;
 }
@@ -3198,8 +3256,22 @@ function readDescriptor(name, m, descriptors, ctx) {
     description: m.description
   };
 }
-function emitsOf(m) {
-  return [.../* @__PURE__ */ new Set([...(m.events ?? []).map((e) => e.emit), ...m.emits ?? []])];
+function emitsOf(m, reads2, ctx) {
+  const installed = new Set(reads2.map((r) => r.accessor));
+  const claimed = (m.events ?? []).filter((e) => holds(e.claim, installed, ctx)).map((e) => e.emit);
+  return [.../* @__PURE__ */ new Set([...claimed, ...m.emits ?? []])];
+}
+function holds(claim, installed, ctx) {
+  if (!claim)
+    return true;
+  if (claim.codecs && (ctx?.codec === void 0 || !claim.codecs.includes(ctx.codec)))
+    return false;
+  if (claim.reads?.some((name) => !installed.has(name)))
+    return false;
+  if (claim.homeBaseAttached !== void 0 && ctx?.homeBaseAttached !== void 0) {
+    return ctx.homeBaseAttached === claim.homeBaseAttached;
+  }
+  return true;
 }
 
 // dist/model/capabilities/video.js
@@ -3704,6 +3776,9 @@ var AiDetectType = {
   vehicle: 4,
   pet: 8
 };
+var CAMERA_AI_CLAIM = { codecs: ["camera"] };
+var VEHICLE_CLAIM = { ...CAMERA_AI_CLAIM, reads: ["aiDetectType"] };
+var DOG_CLAIM = { ...CAMERA_AI_CLAIM, homeBaseAttached: true };
 var SENSITIVITY_SCALES = [
   /** Standalone PIR sensor: five steps counting DOWN. */
   {
@@ -4095,21 +4170,24 @@ var MOTION = {
   events: [
     { source: "push", match: DoorbellPushEvent.MOTION_DETECTION, emit: "motion" },
     { source: "push", match: CusPushEvent.MOTION_SENSOR_PIR, emit: "motion" },
-    { source: "push", match: IndoorPushEvent.CRYING_DETECTION, emit: "cryingDetected" },
-    { source: "push", match: IndoorPushEvent.SOUND_DETECTION, emit: "soundDetected" },
-    { source: "push", match: DoorbellPushEvent.VEHICLE_DETECTION, emit: "vehicleDetected" },
-    { source: "push", match: HB3PairedDevicePushEvent.DOG_DETECTION, emit: "dogDetected" },
+    { source: "push", match: IndoorPushEvent.CRYING_DETECTION, emit: "cryingDetected", claim: CAMERA_AI_CLAIM },
+    { source: "push", match: IndoorPushEvent.SOUND_DETECTION, emit: "soundDetected", claim: CAMERA_AI_CLAIM },
+    { source: "push", match: IndoorPushEvent.PET_DETECTION, emit: "petDetection", claim: CAMERA_AI_CLAIM },
+    { source: "push", match: DoorbellPushEvent.VEHICLE_DETECTION, emit: "vehicleDetected", claim: VEHICLE_CLAIM },
+    { source: "push", match: HB3PairedDevicePushEvent.DOG_DETECTION, emit: "dogDetected", claim: DOG_CLAIM },
     {
       source: "push",
       match: HB3PairedDevicePushEvent.DOG_LICK_DETECTION,
       emit: "dogDetected",
-      payload: { kind: "lick" }
+      payload: { kind: "lick" },
+      claim: DOG_CLAIM
     },
     {
       source: "push",
       match: HB3PairedDevicePushEvent.DOG_POOP_DETECTION,
       emit: "dogDetected",
-      payload: { kind: "poop" }
+      payload: { kind: "poop" },
+      claim: DOG_CLAIM
     }
   ]
 };
@@ -6779,10 +6857,16 @@ var DOORBELL = {
   properties: propertiesOf(DOORBELL_MEMBERS),
   /** Doorbells self-report no single unambiguous param; the model name is the reliable signal. */
   detection: { modelHints: [/doorbell/i] },
-  /** Inbound FCM doorbell events (`DoorbellPushEvent`): ring press, pet, package delivered/taken. */
+  /**
+   * Inbound FCM doorbell events (`DoorbellPushEvent`): ring press and the package trio.
+   *
+   * Pet (3106) is NOT here. The id is declared identically in the doorbell, indoor and HB3-paired
+   * vocabularies, so it belongs to the camera-wide `motion` module that every camera binds; claiming
+   * it here as well would make it a contested id that a doorbell — which has both capabilities —
+   * matches twice, emitting one push as two events.
+   */
   events: [
     { source: "push", match: DoorbellPushEvent.PRESS_DOORBELL, emit: "doorbellPress" },
-    { source: "push", match: DoorbellPushEvent.PET_DETECTION, emit: "petDetection" },
     { source: "push", match: DoorbellPushEvent.PACKAGE_DELIVERED, emit: "packageDelivered" },
     { source: "push", match: DoorbellPushEvent.PACKAGE_TAKEN, emit: "packageTaken" },
     { source: "push", match: DoorbellPushEvent.PACKAGE_STRANDED, emit: "packageStranded" }
@@ -8275,6 +8359,25 @@ var CARPET_STRATEGIES = ["autoRaise", "avoid", "ignore"];
 var CARPET_STRATEGY = { 0: "autoRaise", 1: "avoid", 2: "ignore" };
 var CLEAN_EXTENTS = ["normal", "narrow", "quick"];
 var CLEAN_EXTENT = { 0: "normal", 1: "narrow", 2: "quick" };
+function cleanParamWireValue(names, name) {
+  const found = Object.entries(names).find(([, candidate]) => candidate === name);
+  if (found === void 0)
+    throw new Error(`clean param: ${name} is not a value this setting takes`);
+  return Number(found[0]);
+}
+function writeCleanSetting(p, wrapper, inner, value) {
+  p.sub(wrapper, (w) => {
+    if (value !== 0)
+      w.int(inner, value);
+  });
+}
+function encodeCleanParam(cleanType, cleanExtent, mopLevel) {
+  return rawDp((w) => w.sub(CLEAN_PARAM_FIELD.CONFIGURED, (p) => {
+    writeCleanSetting(p, CLEAN_PARAM_FIELD.CLEAN_TYPE, CLEAN_PARAM_FIELD.VALUE, cleanParamWireValue(CLEAN_TYPE, cleanType));
+    writeCleanSetting(p, CLEAN_PARAM_FIELD.CLEAN_EXTENT, CLEAN_PARAM_FIELD.VALUE, cleanParamWireValue(CLEAN_EXTENT, cleanExtent));
+    writeCleanSetting(p, CLEAN_PARAM_FIELD.MOP_MODE, CLEAN_PARAM_FIELD.MOP_LEVEL, cleanParamWireValue(MOP_LEVEL, mopLevel));
+  }));
+}
 function decodeCleanParamValue(raw, codec, field, inner) {
   if (typeof raw !== "string" || !codec)
     return void 0;
@@ -9954,6 +10057,49 @@ var VACUUM_CLEAN_MEMBERS = {
    * WATCHED: run on a T2351, it started the named scene.
    */
   startScene: method(({ sink }) => (sceneId) => sink.dispatch(aiotDp(VACUUM_DP.MODE_CTRL, encodeSceneClean(sceneId))), "Run a saved cleaning scene by its id (ModeCtrlRequest method 24 over DP 152).", isAiotVacuum),
+  /**
+   * State the cleaning settings a run uses — `CleanParamRequest.clean_param` over DP 154.
+   *
+   * The write counterpart of {@link VACUUM_CLEAN_MEMBERS.cleanType},
+   * {@link VACUUM_CLEAN_MEMBERS.cleanExtent} and {@link VACUUM_CLEAN_MEMBERS.mopLevel}: one message
+   * carries all three, so they are set together rather than through three setters that would each send
+   * the same message with the other two silent.
+   *
+   * **The evidence, and its limit.** The frame is field 1 of `CleanParamRequest`, which carries the
+   * very `CleanParam` this module decodes out of field 1 of the reports a live T2351 sends — the
+   * field numbers, the single-field wrappers and the `mop_mode.level` scale are all read off that
+   * capture, and `encodeCleanParam` writes what `decodeCleanParamValue` reads. What is NOT captured is
+   * the write direction itself. It ships as a method rather than an unverified write because the
+   * hazard that rule answers does not arise here: DP 154 is the robot's own settings report, so a frame
+   * it does not accept leaves those three reads unchanged, where a wrong fire-and-forget command would
+   * look exactly like success.
+   *
+   * Suction is not here. It has its own data point and its own capability — a `fan` field exists in
+   * this message and is deliberately not written, for the same reason it is not read.
+   */
+  setCleanParam: {
+    ...method(({ sink }) => (cleanType, cleanExtent, mopLevel) => sink.dispatch(aiotDp(VACUUM_DP.CLEAN_PARAM, encodeCleanParam(cleanType, cleanExtent, mopLevel))), "Set the cleaning type, extent and mop water level together (CleanParamRequest.clean_param over DP 154).", isAiotVacuum),
+    args: [
+      {
+        name: "cleanType",
+        kind: "enum",
+        values: VACUUM_CLEAN_TYPES,
+        description: "What the robot does with a surface."
+      },
+      {
+        name: "cleanExtent",
+        kind: "enum",
+        values: CLEAN_EXTENTS,
+        description: "How far past the mapped edge a job reaches. Wire order, not app order."
+      },
+      {
+        name: "mopLevel",
+        kind: "enum",
+        values: MOP_LEVELS,
+        description: "How much water the mop lays down. Only meaningful for a clean type that mops."
+      }
+    ]
+  },
   /**
    * Clean the named rooms of a named map (ModeCtrlRequest method 1 over DP 152).
    *
@@ -12992,7 +13138,8 @@ var Device = class _Device {
       details: describeCapabilities(this.actionMap, {
         codec: this.codec,
         model: this.model,
-        capabilities: new Set(this.capabilities)
+        capabilities: new Set(this.capabilities),
+        homeBaseAttached: this.stationSn !== this.sn
       })
     };
   }