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

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

@@ -481,7 +481,7 @@ export declare function buildActions(caps: readonly Capability[], deps: MemberDe
  * @internal
  */
 export declare function describeCapabilities(bound: Partial<DeviceActionMap>, ctx?: AvailabilityContext): CapabilityDescriptor[];
-export type { CommandContext, CapabilityActions, CapabilityStateReader, CapabilityModule, DetectionSpec, CapabilityFrame, CapabilityEvent, InboundSignal, EventMapping, ProductLine, ActionArgSpec, DecodedState, } from "./types.js";
+export type { CommandContext, CapabilityActions, CapabilityStateReader, CapabilityModule, DetectionSpec, CapabilityFrame, CapabilityEvent, InboundSignal, EventClaim, EventMapping, ProductLine, ActionArgSpec, DecodedState, } from "./types.js";
 /**
  * The value-kind vocabulary a read is annotated with, re-exported from the barrel that publishes the
  * read itself, so the union a member's `kind` is drawn from is reachable from the same import.

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

@@ -136,6 +136,45 @@ export interface EventMapping {
      * capture. Return `{}` when this signal doesn't carry the field, so nothing is invented.
      */
     derive?(signal: InboundSignal): Record<string, unknown>;
+    /**
+     * Evidence that this device deals in the classification the id names, for an id whose presence in
+     * the wire vocabulary does not prove it.
+     *
+     * The AI-detection ids are shared verbatim across the camera families, so the id space says what an
+     * integer MEANS and never which units classify that way. A claim is how a mapping states the
+     * evidence that separates them, and it narrows the DESCRIPTION only: {@link EventMapping} stays in
+     * the dispatch index unclaimed, so a device that sends the push still gets the event. Under-reporting
+     * what a device is expected to emit is recoverable; dropping an event it did emit is not.
+     *
+     * Every field must hold — the AND to {@link DetectionSpec}'s OR, because a claim rules a family OUT
+     * rather than finding one more reason to say yes. A fact the context does not carry rules nothing
+     * out: only evidence that positively contradicts the claim withdraws the event.
+     */
+    claim?: EventClaim;
+}
+/**
+ * Evidence separating the families that share one inbound id.
+ *
+ * Both fields are optional and independent; an empty claim asserts nothing and is the same as none.
+ */
+export interface EventClaim {
+    /**
+     * The codecs whose devices issue the id. For an id drawn from a vocabulary one device family owns:
+     * the AI-detection ids belong to the camera families, and a standalone sensor announces its own
+     * motion under a different id entirely.
+     */
+    codecs?: readonly Codec[];
+    /**
+     * Member names whose INSTALLED getter is the evidence — the device reported the parameter behind
+     * the classification, which is the same bar every typed read is held to.
+     */
+    reads?: readonly string[];
+    /**
+     * The topology the id belongs to: `true` for an id only a station's attached device sends, `false`
+     * for one only a standalone unit sends. Compared against {@link AvailabilityContext.homeBaseAttached},
+     * and ignored where that is absent.
+     */
+    homeBaseAttached?: boolean;
 }
 /**
  * A decoded inbound event a capability wants surfaced on the SDK. `event` is the EufyMega event
@@ -197,6 +236,15 @@ export interface AvailabilityContext {
      * `undefined` as an empty set — `ctx.paramIds?.has(dp) ?? false`.
      */
     paramIds?: ReadonlySet<number>;
+    /**
+     * Whether the device hangs off a HomeBase (a `parent_sn` other than its own) rather than standing
+     * alone. A DEVICE fact, not a transport one — the same class of routing evidence as {@link hasP2p} —
+     * which is why it sits here rather than on {@link CommandContext}: it is as true of a described
+     * device as of a commanded one. The `rtsp` capability gates on it because a station serves an
+     * attached camera's stream itself and ignores that camera's authentication setting, so the write
+     * cannot do what its name promises there.
+     */
+    homeBaseAttached?: boolean;
 }
 export interface CommandContext extends AvailabilityContext {
     /** Device channel (0 for standalone, `device_channel` on a HomeBase). */
@@ -259,13 +307,6 @@ export interface CommandContext extends AvailabilityContext {
      * capability uses this to route lock/unlock to P2P vs. reject with a clear MQTT-not-wired error.
      */
     hasP2p?: boolean;
-    /**
-     * Whether the device hangs off a HomeBase (a `parent_sn` other than its own) rather than standing
-     * alone. A DEVICE fact, not a transport one — the same class of routing evidence as {@link hasP2p}.
-     * The `rtsp` capability gates on it because a station serves an attached camera's stream itself and
-     * ignores that camera's authentication setting, so the write cannot do what its name promises there.
-     */
-    homeBaseAttached?: boolean;
     /**
      * Parsed `get_product_data_point` catalog for this device's SKU — present for vacuum/mower devices,
      * absent for all other codecs. Capabilities use it for per-model feature-availability and value-range

package/dist/model/capabilities/vacuum-clean.d.ts

@@ -379,6 +379,23 @@ export type CarpetStrategy = (typeof CARPET_STRATEGIES)[number];
  */
 export declare const CLEAN_EXTENTS: readonly ["normal", "narrow", "quick"];
 export type CleanExtent = (typeof CLEAN_EXTENTS)[number];
+/**
+ * Build a `CleanParamRequest` (DP 154) stating the three cleaning settings a run uses.
+ *
+ * The message is `{ clean_param: CleanParam }` — field 1 of the request, carrying the same `CleanParam`
+ * this module decodes out of field 1 of the reports it receives, so the shape a write sends is the
+ * shape a read has already been proven against on live hardware.
+ *
+ * All three settings are stated together because one message carries all three: a write naming fewer
+ * would be a `CleanParam` with the rest silent, and what a robot does with a half-stated one is not
+ * something this SDK has observed. `clean_times`(7) is never written — the vendor's own field comment
+ * makes zero mean "not stated", so omitting it leaves the robot's configured pass count alone — and
+ * neither is `fan`(6), which belongs to the suction capability's own data point.
+ *
+ * {@link VACUUM_CLEAN_MEMBERS.setCleanParam} dispatches this.
+ * @internal
+ */
+export declare function encodeCleanParam(cleanType: VacuumCleanType, cleanExtent: CleanExtent, mopLevel: MopLevel): string;
 /**
  * Read one setting out of the CONFIGURED `CleanParam` (DP 154), by its field number.
  *
@@ -1963,6 +1980,48 @@ export declare const VACUUM_CLEAN_MEMBERS: {
     readonly startScene: import("./members.js").MethodMember<(sceneId: number) => Promise<void>> & {
         available: (ctx: import("./types.js").CommandContext) => boolean;
     };
+    /**
+     * 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.
+     */
+    readonly setCleanParam: {
+        readonly method: (deps: import("./members.js").MemberDeps) => (cleanType: VacuumCleanType, cleanExtent: CleanExtent, mopLevel: MopLevel) => Promise<void>;
+        readonly description: string;
+        readonly available: ((ctx: import("./types.js").CommandContext) => boolean) & ((ctx: import("./types.js").CommandContext) => boolean);
+        readonly answers?: true;
+        readonly args: readonly [{
+            readonly name: "cleanType";
+            readonly kind: "enum";
+            readonly values: readonly ["sweep", "mop", "sweepAndMop", "sweepThenMop"];
+            readonly description: "What the robot does with a surface.";
+        }, {
+            readonly name: "cleanExtent";
+            readonly kind: "enum";
+            readonly values: readonly ["normal", "narrow", "quick"];
+            readonly description: "How far past the mapped edge a job reaches. Wire order, not app order.";
+        }, {
+            readonly name: "mopLevel";
+            readonly kind: "enum";
+            readonly values: readonly ["low", "middle", "high"];
+            readonly 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).
      *

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

@@ -71,9 +71,34 @@ export declare class MegaApiError extends Error {
  * device-list params carry the same `{param_type, param_value, update_time}` and are not owner-gated.
  */
 export declare const OWNER_ONLY_CODE = 20004;
-/** Thrown when a persisted/expired session is rejected (401). Re-login to recover. */
+/**
+ * Thrown when a persisted/expired session is rejected (401). Re-login to recover.
+ *
+ * It carries the rate the client has already worked out for replacing a rejected token, because the
+ * rejection is where that rate stops being the client's alone: a login driven from here spends the same
+ * session the client's own recovery would have, and repeated logins are what makes an account start
+ * demanding captchas. {@link retryAfterMs} is how long the next replacement is barred for, and
+ * {@link contended} whether this rejection landed inside that bar — the shape repeated displacement has.
+ */
 export declare class SessionExpiredError extends Error {
-    constructor(message: string);
+    /**
+     * 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.
+     */
+    readonly retryAfterMs: number;
+    /**
+     * 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.
+     */
+    readonly contended: boolean;
+    constructor(message: string, opts?: {
+        retryAfterMs?: number;
+        contended?: boolean;
+    });
 }
 /**
  * eufy cloud gateway error codes — the numeric `code` carried in a response envelope alongside the
@@ -223,9 +248,11 @@ export declare class MegaHttpClient {
     private loggingIn;
     /** The one in-flight re-login every call rejected on the same dead token waits on. */
     private 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}. */
     private recoveries;
     private lastRecoveryAt;
+    /** A token of ours has been rejected and not yet replaced — see {@link noteTokenReplacement}. */
+    private rejectedTokenPending;
     constructor(cfg: MegaClientConfig);
     /**
      * Install the session the store holds, if it holds a usable one: the token + its bound ECDH key, skipping
@@ -500,6 +527,26 @@ export declare class MegaHttpClient {
      * and a caller is told the honest reason instead of being served a fight.
      */
     private recoveryDue;
+    /**
+     * 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.
+     */
+    private holdOffRemainingMs;
+    /**
+     * 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.
+     */
+    private noteTokenReplacement;
     /**
      * 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.

package/package.json

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