@mega-yfue/eufy-sdk 0.5.0-beta.87 → 0.5.0-beta.89

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

@@ -122,6 +122,11 @@ export declare function cameraPowerTier(model: string | undefined, capabilities:
  * harvest to report either.
  */
 export declare const CELL_PARAMS: readonly number[];
+/**
+ * The app's charger-state decode: `charging = value ∉ {0,2}`. The app applies this one rule both to a
+ * camera's `BATTERY_STATUS` (2111) and to a keypad's `APP_CMD_KEYPAD_BATTERY_CHARGER_STATE` (1655).
+ */
+export declare function isChargingState(v: string | number | boolean): boolean;
 /**
  * Every `battery` feature, declared once — the property schema, the evidence-gated getters, the derived
  * setters, the intent routes and the descriptions all come out of this table. Order is schema order.
@@ -159,7 +164,7 @@ export declare const BATTERY_MEMBERS: {
         readonly type: "bool";
         readonly kind: "boolean";
         readonly provenance: "apk";
-        readonly coerce: (v: string | number | boolean) => boolean;
+        readonly coerce: typeof isChargingState;
         readonly description: string;
     };
     /**

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

@@ -418,7 +418,7 @@ export interface DeviceActionMap {
     smoke: SmokeActions;
     /** CO-detector reads (read-only): `coDetected`, `lastSeen`. */
     co: CoActions;
-    /** Security-keypad reads (read-only): `rssi`. */
+    /** Security-keypad reads (read-only): `charging`, `rssi`. */
     keypad: KeypadActions;
     /** RTSP publish for a NAS/NVR: `publish`/`withdraw` + `published`, `requireAuth`/`allowAnonymous`, `recordingMode`/`setRecordingMode`. One camera at a time per station. */
     rtsp: RtspActions;

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

@@ -1,13 +1,12 @@
+import { isChargingState } from "./battery.js";
 import { type Surface } from "./members.js";
 import type { CapabilityModule } from "./types.js";
 /**
- * Every `keypad` feature, declared once. Only `rssi` is a verified read.
+ * Every `keypad` feature, declared once. `rssi` is a verified read and `charging` follows the app's own
+ * decode of the keypad's charger state.
  *
- * The battery pair is `unexposed`: both ids are placeholders, and the keypad's real battery state is
- * reported under model-specific params (`keypadBatteryCapState` / `keypadBatteryChargerState`, seen
- * live) whose low/charging semantics are not confirmed. They stay in the schema so a diagnosis can
- * reach them through `getProperty`, with no typed getter asserting a meaning this SDK cannot back.
- * A live probe of the fleet's T8960 confirms neither is reported at all today.
+ * `batteryLow` is `unexposed`: the app maps its param to the same low-battery field the entry and motion
+ * sensors feed, but its value decode is absent from the app's parser, so the polarity is not evidenced.
  *
  * Exported but NOT published: each entry states its wire id and the evidence it was confirmed on,
  * which the reference site does not carry.
@@ -15,36 +14,34 @@ import type { CapabilityModule } from "./types.js";
  */
 export declare const KEYPAD_MEMBERS: {
     /**
-     * `unexposed`, so it reaches a diagnosis through `getProperty` but gets no typed getter. 1103 is a
-     * placeholder AND a likely collision — the app's own param table names 1103 GET_CAMERA_INFO — so a
-     * getter here would be asserting a meaning nothing backs. The keypad's real battery state arrives
-     * under `keypadBatteryCapState`, whose low/charging semantics are not confirmed.
+     * `APP_CMD_KEYPAD_BATTERY_CAP_STATE` (1653). The app's sensor parser maps it to `sensor_is_low_power`,
+     * the field `APP_CMD_ENTRY_SENSOR_BAT_STATE` and `APP_CMD_MOTION_SENSOR_BAT_STATE` decode as a boolean,
+     * yet gives 1653 itself no decode case. `unexposed` until a device confirms which value means low; in
+     * the schema for `getProperty`, absent from the typed surface.
      */
     readonly batteryLow: {
-        readonly param: 1103;
+        readonly param: 1653;
         readonly type: "bool";
         readonly kind: "boolean";
-        readonly provenance: "guessed";
+        readonly provenance: "apk";
         readonly unexposed: true;
         readonly description: string;
     };
     /**
-     * The charging half of the battery pair, `unexposed` for the same reason as `batteryLow`: 1102 is a
-     * placeholder id, and the state the keypad actually reports (`keypadBatteryChargerState`) has no
-     * confirmed value space. In the schema for `getProperty`, absent from the typed surface.
+     * `APP_CMD_KEYPAD_BATTERY_CHARGER_STATE` (1655), decoded the way the app's sensor parser decodes it:
+     * `charging = value ∉ {0,2}` ({@link isChargingState}).
      */
     readonly charging: {
-        readonly param: 1102;
+        readonly param: 1655;
         readonly type: "bool";
         readonly kind: "boolean";
-        readonly provenance: "guessed";
-        readonly unexposed: true;
-        readonly description: "Keypad charging flag. UNVERIFIED: placeholder id pending verification.";
+        readonly provenance: "apk";
+        readonly coerce: typeof isChargingState;
+        readonly description: string;
     };
     /**
-     * The keypad's link quality in dBm — the one verified read in this table, on the same param 1141 the
-     * other sub-1G sensors report signal strength on. Reported as the device measures it: raw dBm, never
-     * normalised to a bar count.
+     * The keypad's link quality in dBm, on the same param 1141 the other sub-1G sensors report signal
+     * strength on. Reported as the device measures it: raw dBm, never normalised to a bar count.
      */
     readonly rssi: {
         readonly param: 1141;
@@ -57,5 +54,5 @@ export declare const KEYPAD_MEMBERS: {
 };
 /** Bound keypad reads — the object returned by `dev.keypad()`. Read-only. */
 export type KeypadActions = Surface<typeof KEYPAD_MEMBERS>;
-/** `keypad` — security keypad. Battery low/charging and signal. Param ids here are placeholders apart from RSSI. */
+/** `keypad` — security keypad. Charging, battery-low and signal. */
 export declare const KEYPAD: CapabilityModule;

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

@@ -33,13 +33,19 @@ export declare const LOCK_SETTING_ID: {
 /**
  * Bound lock controls — the object returned by `dev.lock()`.
  *
- * Everything is DERIVED from `LOCK_MEMBERS`. `lock`/`unlock` and the setting toggles drive any
- * lock-family actuator — currently the T8531 video smart lock and the T85D0 garage door, which share one
- * actuation frame. This module emits ONE transport-neutral intent (identity fields only, no wire bytes,
- * no cipher, no routing key) and names no transport: the command sink routes P2P vs MQTT by the device's
- * topology, and the chosen transport's command router builds the frame + envelope and re-resolves its own
- * routing tail. Which pipe it is does not reach `dev.lock()` — its surface is identical either way,
- * the same way P2P-vs-cloud is hidden for live media.
+ * Everything is DERIVED from `LOCK_MEMBERS`. `lock`/`unlock` drive every lock-family actuator over the
+ * wire its family takes: the shared `ff09` frame on the T8531 video smart lock and the T85D0 garage door,
+ * the T8530 video lock's own `set-payload`, and the keyed-payload envelope on the classic Wi-Fi lock (the
+ * `T8520`-range unit that never negotiates a session key). The setting toggles ride `ff09` only. This
+ * module emits ONE transport-neutral intent per wire (identity fields only, no wire bytes, no cipher, no
+ * routing key) and names no transport: the command sink routes P2P vs MQTT by the device's topology, and
+ * the chosen transport's command router builds the frame + envelope and re-resolves its own routing tail.
+ * Which pipe it is does not reach `dev.lock()` — its surface is identical either way, the same way
+ * P2P-vs-cloud is hidden for live media.
+ *
+ * Classic Wi-Fi lock: `lock()` and `unlock()` are both confirmed on hardware — the bolt moved each way, the
+ * device answered result code 0, and the cloud status followed. That device answers every command, so on it
+ * the two reject on a refusal or an unanswered command as well as on missing identity.
  */
 export type LockActions = Surface<typeof LOCK_MEMBERS>;
 /**
@@ -96,8 +102,8 @@ export declare const LOCK_MEMBERS: {
         readonly description: "Lock battery level 0-100 (verified: param 1101, alias 6001).";
     };
     /**
-     * Link quality in dBm as the lock measures it, on the shared param 1141. Both actuation methods here
-     * are fire-and-forget, so a weak link is silent rather than an error.
+     * Link quality in dBm as the lock measures it, on the shared param 1141. On the `ff09` wire the
+     * actuations are fire-and-forget, so a weak link is silent rather than an error.
      */
     readonly rssi: {
         readonly param: 1141;
@@ -107,11 +113,17 @@ export declare const LOCK_MEMBERS: {
         readonly provenance: "verified";
         readonly description: "Lock signal strength (verified: param 1141 = RSSI).";
     };
-    /** Lock the deadbolt/door. Resolves after sending; does not confirm physical state. */
+    /**
+     * Lock the deadbolt/door. Resolves after sending, without confirming physical state — except on the
+     * classic Wi-Fi lock, which answers: there it rejects on a device refusal or no reply as well.
+     */
     readonly lock: import("./members.js").MethodMember<() => Promise<void>> & {
         available: (ctx: CommandContext) => boolean;
     };
-    /** Unlock the deadbolt/door. Resolves after sending; does not confirm physical state. */
+    /**
+     * Unlock the deadbolt/door. Resolves after sending, without confirming physical state — except on the
+     * classic Wi-Fi lock, which answers: there it rejects on a device refusal or no reply as well.
+     */
     readonly unlock: import("./members.js").MethodMember<() => Promise<void>> & {
         available: (ctx: CommandContext) => boolean;
     };

package/dist/model/device-family.d.ts

@@ -11,6 +11,11 @@ export interface FamilyContext {
      * `"eufy_home_tuya"` devices are on the ThingClips/Tuya Cloud platform, not Anker AIoT MQTT.
      */
     category?: string;
+    /**
+     * Full device serial, when known. The one family split that no type number expresses: the vendor
+     * reuses one DeviceType across generations of a product and distinguishes them by serial.
+     */
+    serial?: string;
 }
 /** Indoor cams, incl. indoor pan/tilt + S350/E30/C-series + mini. */
 export declare const INDOOR_CAMERA_TYPES: ReadonlySet<number>;
@@ -84,3 +89,10 @@ export declare const isAiotVacuum: (ctx: FamilyContext) => boolean;
 export declare const isTuyaVacuum: (ctx: FamilyContext) => boolean;
 /** Video Smart Lock S330, identified by its distinct cloud device type. */
 export declare const isVideoSmartLock: (ctx: FamilyContext) => boolean;
+/**
+ * The classic Wi-Fi smart lock — the unit whose actuation rides a per-command ECDH-wrapped key rather than
+ * the shared `ff09` frame: DeviceType 51 with a serial in the `T8520` range whose seventh character is `2`,
+ * the one range driven on hardware. The DeviceType alone does not identify it, since later units share the
+ * number and take the `ff09` frame, and a device whose serial is unknown is not guessed either way.
+ */
+export declare const isClassicWifiLock: (ctx: FamilyContext) => boolean;

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

@@ -452,6 +452,15 @@ export declare class MegaHttpClient {
     downloadImage(url: string, p2pDid?: string): Promise<Buffer>;
     /** The security-app data host for this region (face recognition, media, etc.). */
     private securityAppHost;
+    /**
+     * The device's long-lived P-256 public key, as the cloud publishes it for key-wrapped commands
+     * (`type=2`): 64 bytes hex with no `04` prefix. A plain authed GET on the security-app host — the
+     * one read here that is neither signed nor body-encrypted, matching how the app fetches it.
+     * Cached per serial for the client's lifetime; the key does not rotate in normal operation.
+     */
+    getDevicePublicKey(deviceSn: string): Promise<string>;
+    /** Per-serial cache for {@link getDevicePublicKey}. */
+    private readonly devicePublicKeys;
     /**
      * Signed+encrypted POST to the security-app data host (face recognition, etc.).
      * Despite the different host, these endpoints use the SAME algo_ecdh pipeline as

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

@@ -100,6 +100,22 @@ export interface EciesUnwrapOptions {
  * decrypted bytes, or `undefined` on any parse / HMAC / cipher failure (fails closed, never throws).
  */
 export declare function eciesUnwrap(envelope: Buffer, eccPrivateKeyHex: string, options?: EciesUnwrapOptions): Buffer | undefined;
+/** The two random inputs of {@link eciesWrap}, injectable so a spec can pin an envelope's bytes. */
+export interface EciesWrapOptions {
+    /** The ephemeral P-256 private key for the exchange (32 bytes); generated fresh when absent. */
+    ephemeralPrivateKey?: Buffer;
+    /** The AES-128-CBC IV, which the envelope carries (16 bytes); random when absent. */
+    iv?: Buffer;
+}
+/**
+ * The sealing counterpart of {@link eciesUnwrap} with `verifyHmac` and `pkcs7` both set.
+ *
+ * Seals `plaintext` for `peerPublicKey` (a P-256 point, compressed or uncompressed) as
+ * `ephemeralPub(33, compressed) ‖ iv(16) ‖ ct ‖ HMAC(32)`: `S = ECDH_X(ephemeral, peer)` →
+ * `kdf = eufyKDF(S)` → `ct = AES-128-CBC(kdf[0:16], iv, PKCS7(plaintext))`, tagged
+ * `HMAC-SHA256(kdf[16:48], iv ‖ ct)`.
+ */
+export declare function eciesWrap(plaintext: Buffer, peerPublicKey: Buffer, options?: EciesWrapOptions): Buffer;
 /**
  * Derive the P2P **level-2** (signCode 2/8) AES-256-GCM session key from a *decrypted*
  * `CMD_GATEWAYINFO` (1100) payload and the station's ECC private key (from `get_ciphers`).

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

@@ -112,6 +112,17 @@ export declare class P2PCommandRouter {
     private readonly cipherKeyCache;
     /** The recording download in flight per station; a station serves one at a time. */
     private readonly recordingDownloads;
+    /**
+     * The `seq_num` last sent to each device over the keyed-payload wire. The device holds a mark for the life
+     * of a P2P connection: the first keyed command on a new connection is accepted at whatever number it
+     * carries and becomes the mark, and after that a number not above the mark is refused with the mark
+     * published ({@link keyedPayloadSeqMark}). Each accepted command moves this to its number, a refusal
+     * moves it to the published mark + 1, and a device absent here has not been sent one in this process and
+     * seeds from a small random number — which a new connection takes as sent.
+     */
+    private readonly keyedSequences;
+    /** The keyed-payload command in flight per device, which the next one for that device waits on. */
+    private readonly keyedQueue;
     constructor(deps: P2PRouterDeps);
     /** Forward one P2P failure once even when both the session listener and startup waiter observe it. */
     private reportError;
@@ -704,6 +715,68 @@ export declare class P2PCommandRouter {
      * boolean, so the first pass carries the failure and the rest are repeats.
      */
     private sendSetPayloadEnvelope;
+    /**
+     * **`keyed-payload-actuate` intent** — the classic Wi-Fi lock's actuation: the sealed fields from
+     * {@link buildKeyedActuatePayload}, sent as a keyed envelope through {@link P2PSession.sendSetPayload}
+     * on the lock's device channel. No session key is waited for — the envelope seals its own per-command
+     * key for the device's public key (fetched from the cloud, cached per serial), so it goes as soon as
+     * the session is up. The device shows the acting member by display name, which lives on the device
+     * record's `member` rather than in the intent, so it is read here and falls back to the account name
+     * the intent carries.
+     *
+     * The device answers, so the outcome is read rather than assumed: {@link awaitKeyedReply} settles each
+     * send on the replies, and resolves a {@link KEYED_PAYLOAD_SEQ_ERROR} refusal with the mark the device
+     * publishes in the refusal's `CMD_DOORLOCK_P2P_SEQ` (1916) twin. On that mark the command resends once,
+     * at mark + 1; a second refusal, or a refusal that published no mark, throws. Commands run one at a time
+     * per device: the replies carry no correlation id, so one command's answer must never be read as
+     * another's.
+     */
+    private sendKeyedPayloadActuate;
+    /** Run `work` once every keyed-payload command already queued for `sn` has settled. */
+    private serializeKeyed;
+    /**
+     * Send one keyed command at the device's next sequence and, on a sequence refusal, resend once at the
+     * mark the refusal published.
+     *
+     * A device's first number in a process is a small random seed — the scale the vendor app's own counters
+     * run at — and every later one is the previous plus one. The device takes the first number on a new
+     * connection as sent, and from then on refuses one not above the mark it holds, stating the mark in the
+     * refusal's `CMD_DOORLOCK_P2P_SEQ` (1916) twin ({@link awaitKeyedReply} resolves the refusal with it).
+     * So a refusal is resolved to that mark and the command resent once at mark + 1, the number the device
+     * accepts after a refusal; a second refusal, or a refusal that carried no mark, throws. The accepted
+     * number is recorded, so the next command starts just above it.
+     *
+     * @param engage whether the command drives to the engaged (locked) state, which its own report states.
+     * @param send dispatches the envelope at the sequence it is given.
+     */
+    private sendKeyedAtSequence;
+    /**
+     * Send one keyed-payload command and read the device's answer for it from the replies on the command's
+     * channel: the `SET_PAYLOAD` echo (a `commandResult`), at once, carrying the result as an int32 — or,
+     * when the echo was not read and the command changed the device's state, the `NOTIFY_PAYLOAD` about two
+     * seconds later carrying the result again as a `P2P_QUERY_STATUS_IN_LOCK` (1955) document. A report
+     * is tied to the command by its `slState`: only one stating the state this command drives to, by
+     * `engage` ({@link keyedPayloadReportCode}), is read as its answer. A report of the other state is a
+     * previous command's, landing after that command settled on its echo, and is ignored.
+     *
+     * - An accepted result (code `0`) settles the command.
+     * - A sequence refusal is stated twice, both about a tenth of a second after the send: the `-151` echo
+     *   and a `CMD_DOORLOCK_P2P_SEQ` (1916) notify whose `seq_num` is the mark the device holds. The
+     *   resolved value carries that mark, so the caller resends just above it. Collection runs for
+     *   {@link KEYED_REFUSAL_TWIN_MS} after the first of the two, so both land and neither is left on the
+     *   channel for the resend to read as its own answer, and either one alone still resolves the refusal.
+     * - No reply within {@link KEYED_REPLY_MS} is a command that never landed, and rejects.
+     *
+     * Both listeners are armed before the send, and only replies on `channel` are read. The channel names
+     * the device, not the command: every other P2P write a lock takes waits for a level-2 key this device
+     * never negotiates, so nothing else the SDK sends can draw a reply here, and a future intent on this
+     * wrapper has to share {@link serializeKeyed}.
+     */
+    private awaitKeyedReply;
+    /** How long a keyed-payload command waits for any reply before it is taken as never having landed. */
+    private static readonly KEYED_REPLY_MS;
+    /** How long a refusal collects its two statements — the `-151` echo and the mark notify — before resolving. */
+    private static readonly KEYED_REFUSAL_TWIN_MS;
     /**
      * **`ff09-actuate` intent** — build the `ff09` AES-128-CBC frame ({@link buildFf09Frame}, shared with the
      * MQTT transport — see `transport/ff09.ts`) and dispatch it in the `1940` TRANSFER_PAYLOAD envelope

package/dist/transport/p2p/keyed-payload.d.ts

@@ -0,0 +1,112 @@
+import type { Ff09Identity } from "../../core/contracts.js";
+/**
+ * Keyed-payload envelope — the `SET_PAYLOAD` (1350) shape the classic Wi-Fi smart lock takes for its
+ * actuation. There is no session key: every command carries its OWN fresh AES-128 key, sealed for the
+ * device's long-lived P-256 public key (published by the cloud, one per device), and the inner JSON is
+ * AES-128-CBC/PKCS#7 under that key. This module builds the two sealed fields; `P2PSession.sendSetPayload`
+ * wraps them in the ordinary envelope and carries a keyed one in the clear, as the vendor app sends it.
+ *
+ * ## Wire
+ *
+ * ```
+ *   { key: <keyBlobHex>, account_id: <adminUserId>, cmd: <opcode>, mChannel: <ch>, mValue3: 0,
+ *     payload: <base64(AES-128-CBC(aesKey, iv, innerJson))> }
+ * ```
+ * `iv` = ASCII(deviceSn) zero-padded/truncated to 16 bytes. `aesKey` = 16 random bytes, spelled as 32
+ * UPPERCASE hex characters — the hex SPELLING is what the key blob seals, not the raw bytes.
+ *
+ * `key` (hex) is the ECIES envelope {@link eciesWrap} produces for the device's public key over that
+ * spelling: `compressedEphemeralPub(33) ‖ nonce(16) ‖ sealedKey(48) ‖ hmac(32)`.
+ *
+ * Inner JSON for the actuation opcode, `P2P_ON_OFF_LOCK` (1961): `{shortUserId, slOperation: 1|0, userId,
+ * userName, seq_num}`.
+ *
+ * ## Answer
+ *
+ * The device answers every command at once with an int32 result on the `SET_PAYLOAD` echo — `0`
+ * accepted, {@link KEYED_PAYLOAD_SEQ_ERROR} when `seq_num` is not above the mark it holds — and, when the
+ * command changed its state, about two seconds later with a `NOTIFY_PAYLOAD` whose JSON carries
+ * `P2P_QUERY_STATUS_IN_LOCK` (1955) as `cmd`, the result again under `payload.code` and the state reached
+ * under `payload.slState` ({@link keyedPayloadReportCode} reads the code of the report stating the state
+ * a command drives to). A command it was already in the state of draws the echo alone.
+ *
+ * A refusal carries a second `NOTIFY_PAYLOAD`, `CMD_DOORLOCK_P2P_SEQ` (1916), whose `payload.seq_num`
+ * ({@link keyedPayloadSeqMark}) is the mark the device holds — so a refused command hands back the exact
+ * number to resend above, with no searching. The mark lives with the P2P connection: the first keyed
+ * command on a new connection is accepted at whatever number it carries.
+ *
+ * The command ids are {@link CommandType}'s; the inner field names follow a third-party reverse-engineering
+ * project, a name source only.
+ */
+/**
+ * The int32 result the device answers a command with when its `seq_num` is not above the mark it holds for
+ * the connection. The command is dropped untried, so this is a retry signal rather than a failure: resend
+ * above the mark. The refusal publishes that mark in its `CMD_DOORLOCK_P2P_SEQ` (1916) twin
+ * ({@link keyedPayloadSeqMark}), so the resend goes to the next number rather than searching for it.
+ */
+export declare const KEYED_PAYLOAD_SEQ_ERROR = -151;
+/** Knobs a spec injects to make the otherwise random envelope deterministic, plus the sequence it carries. */
+export interface KeyedPayloadRandomness {
+    /** The per-command AES key (16 bytes). */
+    aesKey?: Buffer;
+    /** The CBC nonce sealing that key inside the blob (16 bytes). */
+    nonce?: Buffer;
+    /** The ephemeral P-256 private key for the ECDH exchange (32 bytes). */
+    ephemeralPrivateKey?: Buffer;
+    /** The `seq_num` the inner JSON carries, issued by the sender. */
+    seqNum: number;
+}
+/**
+ * The cipher IV the device derives from its own serial: ASCII bytes, zero-padded to 16. It is the same for
+ * every command to a device, which is sound only because {@link buildKeyedActuatePayload} seals each command
+ * under a key minted for it alone — no two messages ever share a key with this IV.
+ */
+export declare function serialIv(deviceSn: string): Buffer;
+/** Spell 16 key bytes as the 32 uppercase hex characters the wire seals. */
+export declare function spellAesKey(key: Buffer): string;
+/**
+ * Seal a per-command AES key for the device's P-256 public key: the {@link eciesWrap} envelope over the
+ * key's hex spelling, as hex.
+ * @param aesKeyHex the 32-hex-char key spelling (what gets sealed — as ASCII).
+ * @param devicePublicKeyHex the device's uncompressed public key WITHOUT the `04` prefix (64 bytes hex).
+ */
+export declare function buildKeyBlob(aesKeyHex: string, devicePublicKeyHex: string, rnd?: Pick<KeyedPayloadRandomness, "nonce" | "ephemeralPrivateKey">): string;
+/** AES-128-CBC/PKCS#7 the inner JSON under the per-command key, IV from the serial; base64 out. */
+export declare function sealInnerPayload(innerJson: string, aesKeyHex: string, deviceSn: string): string;
+/** The two sealed fields of a keyed envelope; the sender supplies the rest of the `SET_PAYLOAD` value. */
+export interface KeyedActuatePayload {
+    /** The sealed per-command key — the value's `key` field, hex. */
+    key: string;
+    /** The inner JSON sealed under that key — the value's `payload` field, base64. */
+    payload: string;
+}
+/**
+ * Build the sealed fields of the classic Wi-Fi lock's actuation.
+ * @param id the acting identity + direction.
+ * @param devicePublicKeyHex the device's public key from the cloud (no `04` prefix).
+ * @param userName the acting member's display name as the device shows it in its log.
+ */
+export declare function buildKeyedActuatePayload(id: Ff09Identity, devicePublicKeyHex: string, userName: string, rnd: KeyedPayloadRandomness): KeyedActuatePayload;
+/**
+ * The result a `NOTIFY_PAYLOAD` document reports for a keyed command driving to a state. The device sends
+ * one once a keyed command has changed its state, `{cmd, payload: {code, slState, …}}` with `cmd`
+ * `P2P_QUERY_STATUS_IN_LOCK` (1955) in {@link CommandType}, `payload.code` being the command's result and
+ * `payload.slState` the state reached. Answers `payload.code` when it is a number and `payload.slState` is
+ * the state the command drives to: `"4"` engaged (locked) when `engage`, `"3"` released (unlocked) when
+ * not, the values of the lock's state param 6000 as the device spells them. Answers `undefined` for any
+ * other document, a report of the other state included: that one answers some other command.
+ */
+export declare function keyedPayloadReportCode(json: {
+    cmd?: number;
+    payload?: unknown;
+} | undefined, engage: boolean): number | undefined;
+/**
+ * The sequence mark a `NOTIFY_PAYLOAD` document publishes. The one that rides a sequence refusal is
+ * `{cmd, payload: {lock_cmd, seq_num}}` with `cmd` `CMD_DOORLOCK_P2P_SEQ` (1916) in {@link CommandType},
+ * `payload.seq_num` being the mark the device holds on this connection. Answers that number, or
+ * `undefined` for any other document.
+ */
+export declare function keyedPayloadSeqMark(json: {
+    cmd?: number;
+    payload?: unknown;
+} | undefined): number | undefined;

package/dist/transport/p2p/p2p-session.d.ts

@@ -706,6 +706,10 @@ export declare class P2PSession extends EventEmitter {
      * Low-level: send a `CMD_SET_PAYLOAD` (1350) wrapping `{account_id, cmd:<subCmd>, mChannel,
      * payload, transaction}` over the level-1 channel. The reply arrives as a `NOTIFY_PAYLOAD`
      * (1351) frame (level-1 decrypted, surfaced via the `data` event / `frame.json`).
+     *
+     * `opts.key` makes it a keyed envelope: the sealed per-command key rides ahead of the other fields
+     * as the value's `key`, and the value goes out unencrypted, encryption-type 0, with `=` written
+     * `=` — the form the vendor app sends one in, and the one form the device reads it in.
      */
     sendSetPayload(subCmd: number, payload?: unknown, opts?: {
         accountId?: string;
@@ -713,6 +717,7 @@ export declare class P2PSession extends EventEmitter {
         omitPayload?: boolean;
         wrapCmd?: number;
         rawValue?: Record<string, unknown>;
+        key?: string;
     }): void;
     /**
      * Request the on-device edge-AI face roster over P2P. `COMMAND_GET_LOCAL_FACES` (1194) =

package/package.json

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