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

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

@@ -550,7 +550,7 @@ export { HubAlarmTone, type HubAlarmToneValue } from "./siren.js";
  * RoboVac activity and clean type are the declared returns of the public `dev.vacuumClean()` getters,
  * so both unions are published.
  */
-export type { VacuumActivity, VacuumCleanType, CarpetStrategy, CleanExtent } from "./vacuum-clean.js";
+export type { VacuumActivity, VacuumCleanType, CarpetStrategy, CleanExtent, VacuumRoomTarget, VacuumZoneTarget, } from "./vacuum-clean.js";
 /** The lists those unions are taken from — published because each union names its own. */
 export { VACUUM_ACTIVITIES, VACUUM_CLEAN_TYPES, CARPET_STRATEGIES, CLEAN_EXTENTS, MOP_LEVELS } from "./vacuum-clean.js";
 export { SuctionLevel, suctionLevelName, type SuctionLevelValue } from "./suction.js";

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

@@ -192,35 +192,27 @@ export declare const ModeCtrlMethod: {
     readonly STOP_SMART_FOLLOW: 18;
     readonly START_GLOBAL_CRUISE: 20;
 };
-/**
- * The methods that carry a `Param` oneof — room, zone, goto, schedule, cruise and scene cleans.
- *
- * Deliberately absent from {@link ModeCtrlMethod}. Each needs an argument the caller has to supply and
- * this SDK cannot yet answer: a room or zone id comes from map data, which is not decodable here, and a
- * coordinate is signed centimetres in a frame no capture has pinned. Listing their numbers beside the
- * parameterless ones would invite a caller to send one with an empty payload, which is a valid frame
- * meaning something nobody intended.
- */
-/**
- * Encode a `ModeCtrlRequest` protobuf (DP 152) as a DP value: `varint(bodyLen) ++ {method:1, seq:2}`.
- *
- * Built on {@link RawDpWriter} rather than hand-rolled bytes. The frame is unchanged and the existing
- * byte-level test is what proves it — that test was written against a live T2351 capture, so it holds
- * the writer to the wire rather than to this function's own idea of the wire.
- *
- * Method 0 (START_AUTO_CLEAN) is omitted rather than written as an explicit zero, per the proto3
- * default-field rule and confirmed on that same capture. The writer deliberately does not apply that
- * rule itself: whether an explicit zero and an absent field mean the same thing is the
- * message's business, not the encoder's.
- * @internal
- */
 /**
  * The area-selecting `ModeCtrlRequest` methods, and the `Param` field each one's payload rides in.
  *
  * Kept apart from {@link ModeCtrlMethod} because these are a different kind of thing: a parameterless
  * verb is complete on its own, whereas each of these is meaningless without an argument the caller has
  * to supply. Sending one with an empty payload is a well-formed frame that means something nobody
- * intended, which is exactly why the numbers do not sit beside the others.
+ * intended, which is exactly why the numbers do not sit beside the others. Each verb built on one takes
+ * its argument in the signature: {@link VACUUM_CLEAN_MEMBERS.startScene},
+ * {@link VACUUM_CLEAN_MEMBERS.cleanRooms} and {@link VACUUM_CLEAN_MEMBERS.cleanZones}.
+ *
+ * The outer frame these ride in is byte-verified on a live T2351, and `SCENE`, `SELECT_ROOMS` and
+ * `SELECT_ZONES` have each since been RUN on a T2351 and did what they name — so their numbers rest on
+ * observed behaviour rather than on the vendor's definition alone.
+ *
+ * That distinction is the whole point of checking, and this is the one place it is argued: an AIoT
+ * data-point write is fire-and-forget, so a wrong number would be a different command arriving and
+ * looking exactly like success, which no frame check could catch. Watching the number is the only thing
+ * that rules it out.
+ *
+ * `GOTO` carries no encoder because a goto point is a coordinate no read on this SDK supplies, where a
+ * scene id and a map id both arrive on DP 180.
  */
 export declare const ModeCtrlParamMethod: {
     /** `START_SELECT_ROOMS_CLEAN` — clean the named rooms of a named map. */
@@ -267,7 +259,7 @@ export interface VacuumZoneTarget {
  * `mapId` is required and has no default, deliberately. The obvious shortcut is to assume the map a
  * single-floor home would have; on a two-floor home that silently sends the robot's ids against the
  * wrong floor's map. A caller that cannot name the map cannot safely make this call, and saying so is
- * better than picking for them.
+ * better than picking for them. {@link VACUUM_CLEAN_MEMBERS.cleanRooms} dispatches this.
  * @internal
  */
 export declare function encodeSelectRoomsClean(mapId: number, rooms: readonly VacuumRoomTarget[], cleanTimes?: number): string;
@@ -276,8 +268,25 @@ export declare function encodeSelectRoomsClean(mapId: number, rooms: readonly Va
  * @internal
  */
 export declare function encodeSelectZonesClean(mapId: number, zones: readonly VacuumZoneTarget[]): string;
-/** Build a scene clean, which needs only the scene's own id. @internal */
+/**
+ * Build a scene clean, which needs only the scene's own id — `VacuumScene.id`, as DP 180 reports it.
+ * {@link VACUUM_CLEAN_MEMBERS.startScene} dispatches this.
+ * @internal
+ */
 export declare function encodeSceneClean(sceneId: number): string;
+/**
+ * Encode a `ModeCtrlRequest` protobuf (DP 152) as a DP value: `varint(bodyLen) ++ {method:1, seq:2}`.
+ *
+ * Built on {@link RawDpWriter} rather than hand-rolled bytes. The frame is unchanged and the existing
+ * byte-level test is what proves it — that test was written against a live T2351 capture, so it holds
+ * the writer to the wire rather than to this function's own idea of the wire.
+ *
+ * Method 0 (START_AUTO_CLEAN) is omitted rather than written as an explicit zero, per the proto3
+ * default-field rule and confirmed on that same capture. The writer deliberately does not apply that
+ * rule itself: whether an explicit zero and an absent field mean the same thing is the
+ * message's business, not the encoder's.
+ * @internal
+ */
 export declare function encodeModeCtrl(method: number, seq: number): string;
 /**
  * Every value {@link VacuumActivity} can take, as data — the read's declared domain, so the schema a
@@ -1941,6 +1950,46 @@ export declare const VACUUM_CLEAN_MEMBERS: {
     readonly pauseCleaning: import("./members.js").MethodMember<() => Promise<void>> & {
         available: (ctx: import("./types.js").CommandContext) => boolean;
     };
+    /**
+     * Run a saved cleaning scene by its id (ModeCtrlRequest method 24 over DP 152).
+     *
+     * The id is the device's own, as {@link VACUUM_CLEAN_MEMBERS.scenes} reports it — `VacuumScene.id`
+     * off the `SceneResponse` on DP 180. A scene the device reports invalid stays reportable and running
+     * it is still a well-formed request; `VacuumScene.invalidReason` says why the device will refuse.
+     *
+     * Frame shape is byte-proven against the shared outer `ModeCtrlRequest`, and method 24 has been
+     * WATCHED: run on a T2351, it started the named scene.
+     */
+    readonly startScene: import("./members.js").MethodMember<(sceneId: number) => Promise<void>> & {
+        available: (ctx: import("./types.js").CommandContext) => boolean;
+    };
+    /**
+     * Clean the named rooms of a named map (ModeCtrlRequest method 1 over DP 152).
+     *
+     * `mapId` has no default and that is deliberate: room ids are per map, so assuming the map a
+     * single-floor home would have sends a two-floor home's ids against the wrong floor. `SceneInfo.mapid`
+     * on DP 180 and a scheduled rooms-clean's `map_id` are the two real map ids the device reports.
+     *
+     * `cleanTimes` is how many passes to make over the set; rooms with no `order` are visited in the
+     * order given.
+     *
+     * Frame shape is byte-proven against the shared outer `ModeCtrlRequest`, and method 1 has been
+     * WATCHED: run on a T2351, it cleaned the rooms named.
+     */
+    readonly cleanRooms: import("./members.js").MethodMember<(mapId: number, rooms: readonly VacuumRoomTarget[], cleanTimes?: number) => Promise<void>> & {
+        available: (ctx: import("./types.js").CommandContext) => boolean;
+    };
+    /**
+     * Clean the given rectangles of a named map (ModeCtrlRequest method 2 over DP 152).
+     *
+     * Corners are SIGNED centimetres in the map's own frame, whose origin sits wherever the robot first
+     * mapped from — negative coordinates are ordinary and are ZigZag-encoded, not written as plain
+     * varints. Same `mapId` reasoning as {@link VACUUM_CLEAN_MEMBERS.cleanRooms}, and the same evidence:
+     * method 2 was run on a T2351 and cleaned the rectangles given.
+     */
+    readonly cleanZones: import("./members.js").MethodMember<(mapId: number, zones: readonly VacuumZoneTarget[]) => Promise<void>> & {
+        available: (ctx: import("./types.js").CommandContext) => boolean;
+    };
 };
 /** `vacuum_clean` — core RoboVac scalar state + decoded activity: power, activity, volume, battery. */
 export declare const VACUUM_CLEAN: CapabilityModule;

package/dist/transport/p2p/live-trace.d.ts

@@ -188,6 +188,22 @@ export type LiveTrace =
  | {
     phase: "path-stale";
     silentMs: number;
+}
+/**
+ * A stream received nothing on its own channel for the stall window, and what was done about it.
+ *
+ * A station that switches to a sibling leaves the stream it was serving with no frames, no error and no
+ * stop, so this silence is the only statement that it happened. `reasserted` re-issued the media start,
+ * which is the repair; `declined` left the channel alone because nothing is attached to this pull and
+ * taking the station back would take it from a camera someone is watching.
+ *
+ * Media still arriving means this never fires, so a picture that stopped advancing while this is silent
+ * stopped for a reason upstream of the station's attention.
+ */
+ | {
+    phase: "channel-silent";
+    silentMs: number;
+    outcome: "reasserted" | "declined";
 };
 /**
  * Record one startup observation at debug level.

package/dist/transport/p2p/media.d.ts

@@ -34,11 +34,22 @@ export declare function openLiveStream(session: P2PSession, opts?: LiveStreamOpt
  * The header states the stream's geometry when the capture started, and a stream that reconfigures
  * mid-burst leaves it describing something the returned bytes contradict; the return value describes an
  * image, so the image is its source of truth.
+ *
+ * The consumer is detached the moment the collected run is complete, and the decode that follows holds no
+ * station: it works on bytes already in memory. A station serves one camera at a time and the SDK refuses a
+ * second channel on one that is busy, so a still that kept its pull attached across its own decode would deny
+ * that station to every live request for the length of an FFmpeg run — measured on a real base as a live
+ * request refused 370ms after the still it was waiting on had already collected everything it needed.
+ *
+ * `signal` ends the collection itself, not only the wait for it, and rejects with the signal's own reason
+ * because the abandonment is the caller's fact and not a failure of the source. It reaches only the
+ * collection: past that the station is already free, so there is nothing left for it to release.
  */
 export declare function captureSnapshotFromShared(source: SharedLiveSource, opts?: {
     timeoutMs?: number;
     collectMs?: number;
     skipKeyframes?: number;
+    signal?: AbortSignal;
     logger?: Logger;
     ffmpegLevel?: FfmpegLevel;
     ffmpegPath?: string;

package/package.json

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