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

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

@@ -50,9 +50,28 @@ export declare function setJsonRaw(cmd: number, data: Record<string, unknown>, c
  * Set a param carried in the `SET_PAYLOAD` (1350) envelope — `{account_id,cmd,mChannel,mValue3:cmd,
  * payload}`, GCM signCode 8 — NOT the bare `{commandType,data}` 1700 wrapper `setJson` uses. The wire
  * eufy uses for a few doorbell controls (status-LED 1716 `{light_enable}`). Level-2 by default; the
- * sink resolves the session/account_id and replays the frame. Pass `form: "auto"` when the envelope is
- * also valid at level 1, so a STANDALONE device — which never negotiates a level-2 key — can receive it
- * instead of failing outright.
+ * sink resolves the session/account_id and replays the frame.
+ *
+ * ## When this envelope takes `form: "auto"`
+ *
+ * Left at the default the frame is level-2 ONLY, and on a station holding no level-2 key that does not
+ * fail — it WAITS: the transport spends the full level-2 grace, re-prompts, spends it again, and only
+ * then throws. Every caller with a shorter bound sees a hang rather than a refusal, so a control on a
+ * device that may be its own keyless station is effectively unreachable. `"auto"` hands the choice to
+ * the session (`sendBySessionLevel`), which seals level-2 wherever a key exists — unchanged for a
+ * HomeBase — and level-1 where none does.
+ *
+ * Two conditions, and BOTH have to hold:
+ *
+ *  1. **`mValue3` is passed explicitly as 0.** The level-1 form of this envelope writes `mValue3:0`
+ *     itself, while the level-2 form defaults it to the sub-command — so a command that passes 0 sends
+ *     byte-identical JSON either way and `"auto"` only changes the seal. A command that OMITS `mValue3`
+ *     would send a DIFFERENT object at level 1 than the one captured at level 2; that is a new wire
+ *     needing its own evidence, not a downgrade, and it stays pinned until something captures it.
+ *  2. **The device can be its own station.** A camera or doorbell may be standalone; a HomeBase, and an
+ *     accessory whose session IS its HomeBase's, always holds a key. Where a key is structurally
+ *     guaranteed, staying pinned is the honest behaviour: a keyless station there is an anomaly, and
+ *     throwing says so where a silently-ignored level-1 frame would look like success.
  */
 export declare function setPayload(cmd: number, payload: Record<string, unknown>, ctx: CommandContext, mValue3?: number, channel?: number, form?: ScalarForm): Command;
 /**

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

@@ -72,6 +72,10 @@ export declare const ARMING_CMD: {
      * first, then `schedule` 2, `custom2` 4, `custom3` 5, `off` 6 and `geo` 47 — each sent as this exact
      * frame and each observed to bring MODE_SWITCH back, so all nine are settable. `ARMING_MODE_WIRE` has
      * the per-value evidence and the dates.
+     *
+     * The ENCRYPTION LEVEL is the session's to pick (`"auto"`), not this command's: the T8030 the envelope
+     * was captured on holds a level-2 key and seals it level-2, while an own-session camera that never
+     * negotiates one carries the same envelope level-1. See `armingCommand`.
      */
     readonly SET_ARMING: 1224;
     /**

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

@@ -106,6 +106,10 @@ export declare const CONTACT_MEMBERS: {
      * `1350` SET_PAYLOAD, `mChannel` = the device channel, `mValue3` 0, payload carrying the channel and a
      * transaction stamp — the byte-shape of the app's own captured frame. Out of range is refused rather
      * than clamped: the app's slider has no values outside it, so one is a caller error, not a nudge.
+     *
+     * Level-2 only, though the `mValue3` 0 would allow `"auto"`: an entry sensor's session IS its
+     * HomeBase's, which always holds a key — the second of `setPayload`'s two conditions, not an oversight
+     * of the first.
      */
     readonly alarmVolume: {
         readonly param: 1508;

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

@@ -199,8 +199,12 @@ export declare function savePresetCommand(id: number, ctx: CommandContext): [Com
  *
  * 6242 sets the default to the preset the camera is **currently parked on**. To move the default, park
  * the camera on `presetId` first — `preview(presetId)`, let the pan finish, then `setDefault(presetId)`.
- * Sent while the camera is elsewhere, it has no effect. The parser is topology-agnostic; the router
- * picks the encryption level (L1/L2) by topology.
+ * Sent while the camera is elsewhere, it has no effect.
+ *
+ * Level-2 only, unlike `zoom` beside it: this frame carries the envelope's DEFAULT `mValue3` (the
+ * sub-command), which the level-1 form cannot express — it writes 0. Downgrading it would send an
+ * object nothing has captured, so it stays pinned and is unreachable on a keyless standalone camera
+ * until one is. See `setPayload`'s two conditions.
  */
 export declare function setDefaultPositionCommand(presetId: number, ctx: CommandContext): Command;
 /**

package/dist/transport/p2p/command-router.d.ts

@@ -675,6 +675,13 @@ export declare class P2PCommandRouter {
      * standalone camera never negotiates a level-2 key, so pinning this to level 2 makes the envelope
      * unreachable on exactly the devices that serve their own RTSP stream. Verified live: a standalone
      * camera accepts the level-1 form. With no `form` (default) it stays level-2 only.
+     *
+     * Both seals REPLAY the frame {@link DIRECT_CMD_SENDS}× at 200ms, as every other fire-and-forget
+     * control on this router does: these are unacknowledged datagrams, and a level-1 device is the one
+     * least able to afford a single dropped one — it has no reply, no readback here, and nothing that
+     * would tell a caller the write was lost rather than refused. The level-1 form reports delivery by
+     * throwing (`sendSetPayload` throws when the session has no address) rather than by returning a
+     * boolean, so the first pass carries the failure and the rest are repeats.
      */
     private sendSetPayloadEnvelope;
     /**

package/package.json

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