@mega-yfue/eufy-sdk 0.5.0-beta.9 → 0.5.0-beta.90

package/dist/transport/rtc/signaling.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The T9000's signalling channel: the WebSocket through which a client and a HomeBase S1 Pro agree on a
+ * WebRTC session. It is the wire the security.eufy.com web client uses (`/v1/rtc/ws/join`), and the hub
+ * accepts it from any client presenting the account's mega token.
+ *
+ * Sequence:
+ *
+ *   1. `GET https://<smart host>/v1/smart/nvr/ws/sign` with the mega token → a `sign` blob.
+ *   2. WebSocket to `wss://<smart host>/v1/rtc/ws/join?reqtype=nvr`, subprotocols `["v1", <base64url
+ *      JSON>]` carrying the cluster region, station serial, token, `gtoken` and the sign. HTTP headers on
+ *      the upgrade alone are refused: the JSON subprotocol is what authenticates.
+ *   3. `action 1` auth on open; `action 3` session messages after: `scall` (start), `info` (SDP and
+ *      trickle ICE), `ack`, `hangup`. Every session message carries an HMAC-SHA256 `account` over
+ *      `channelId + adminUserId + ts`, keyed by the token.
+ *
+ * Region is two values: the HTTP sign request names the account's **country** (`Web-Country`), the
+ * WebSocket payload names the **cluster**, the shard prefix uppercased (`ie-pr` → `IE`). The smart host
+ * is `security-smart` for `us` and `security-smart-<prefix>` for any other shard.
+ *
+ * `fetch` and the `WebSocket` constructor are injectable.
+ */
+import { EventEmitter } from "node:events";
+import { type Logger } from "../../core/logger.js";
+/** The portal's origin; the sign endpoint and the socket upgrade both check it. */
+export declare const PORTAL_ORIGIN = "https://security.eufy.com";
+/** The hub drops an idle signalling socket after ~83 s; re-sending auth inside that keeps it. */
+export declare const SIGNALING_KEEPALIVE_MS = 25000;
+/** How long the socket has to open after the sign. */
+export declare const SIGNALING_CONNECT_TIMEOUT_MS = 15000;
+/** Outer wire envelope. */
+export interface RtcWsEnvelope {
+    msgid: string;
+    data: string;
+}
+/** Inner message (the envelope's `data`, JSON-parsed). */
+export interface RtcInnerMessage {
+    code?: number;
+    action?: number;
+    sessionId?: string;
+    sn?: string;
+    subSn?: string;
+    channelId?: number;
+    isResponse?: number;
+    dataType?: string;
+    source?: string;
+    ts?: number;
+    data?: string;
+    msgid?: string;
+}
+/** What a socket event carries; only the fields each event type fills are read. */
+export interface SignalingSocketEvent {
+    data?: unknown;
+    code?: number;
+    reason?: string;
+}
+/** The subset of a `WebSocket` the client uses. */
+export interface SignalingSocket {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: "open" | "message" | "close" | "error", listener: (ev: SignalingSocketEvent) => void): void;
+}
+export interface SignalingSocketInit {
+    /** The subprotocols; slot 2 carries the base64url auth JSON. */
+    protocols: string[];
+    /** The upgrade Origin, which the server checks like the sign call. */
+    origin: string;
+}
+export type SignalingSocketFactory = (url: string, init: SignalingSocketInit) => SignalingSocket;
+export interface RtcSignalingOptions {
+    /** Full SDP (`call`) or compact SDP (`scall`, the default). */
+    signalingMode?: "call" | "scall";
+    /** The mega session's auth token. */
+    authToken: string;
+    /** The `gtoken` header value the mega session's authed HTTP calls carry. */
+    gtoken: string;
+    stationSn: string;
+    /** The station's `member.admin_user_id`, the account the session HMAC names. */
+    adminUserId: string;
+    /** The mega shard the account lives on; picks the host and the cluster name. */
+    shard: string;
+    /** The account's ISO country, sent on the sign request (`Web-Country`). */
+    country: string;
+    fetch?: typeof fetch;
+    createSocket?: SignalingSocketFactory;
+    logger?: Logger;
+    now?: () => number;
+    makeMsgId?: () => string;
+}
+export interface RtcSignalingEvents {
+    message: [inner: RtcInnerMessage, envelope: RtcWsEnvelope];
+    open: [];
+    close: [code: number, reason: string];
+    error: [err: Error];
+}
+/** The portal's `account` field: HMAC-SHA256 of `channelId + adminUserId + ts`, keyed by the token. */
+export declare function sessionAccount(channelId: number, adminUserId: string, ts: number, authToken: string): string;
+export declare class RtcSignalingClient extends EventEmitter<RtcSignalingEvents> {
+    private readonly opts;
+    private ws?;
+    private sign?;
+    private keepalive?;
+    private readonly wsUrl;
+    private readonly signUrl;
+    private readonly wsRegion;
+    private readonly fetchImpl;
+    private readonly createSocket;
+    private readonly logger;
+    private readonly now;
+    private readonly makeMsgId;
+    constructor(opts: RtcSignalingOptions);
+    get isOpen(): boolean;
+    /** Step 1: the sign blob the socket and every auth message carry. A non-JSON body is reported by status. */
+    fetchSign(): Promise<string>;
+    /**
+     * Step 2: open the socket and send the first auth; resolves on `open`. A socket that closes or errors
+     * before it ever opened rejects, so the call always settles.
+     */
+    connect(): Promise<void>;
+    /** `action 1`, also what keeps the socket alive when re-sent. */
+    sendAuth(sign?: string): void;
+    /**
+     * `action 3`, a session message on channel 0, the hub's own session; `scall` opens the negotiation.
+     * `subSn` is empty for the hub's session.
+     */
+    sendSession(dataType: string, payload?: Record<string, unknown>): void;
+    sendCall(): void;
+    sendAck(): void;
+    /** The SDP answer, encoded for the negotiated call format, in an `info`. */
+    sendInfoSdp(sdp: string): void;
+    /** Trickle a candidate on the session's channel, like its SDP answer. An empty candidate ends them. */
+    sendInfoCandidate(candidate: string): void;
+    sendHangup(): void;
+    close(): void;
+    private startKeepalive;
+    private stopKeepalive;
+    private sendEnvelope;
+    private handleWireMessage;
+}

package/dist/transport/token-echo.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Strip a token the gateway echoed back into its own error message.
+ *
+ * `"token not exist, token = <the rejected token>"` is the vendor's wording, and that message travels into the
+ * error the SDK surfaces. A credential that has just been rejected is still a credential, and it is
+ * never the part of the message that explains anything.
+ */
+export declare function withoutTokenEcho(text: string): string;

package/dist/transport/tuya/account.d.ts

@@ -1,14 +1,17 @@
-/** Username/plaintext prefix the app prepends to the eufy user id. */
-export declare const TUYA_USERNAME_PREFIX = "eufyhome-";
+/**
+ * Username/plaintext prefix the app prepends to the eufy user id. The production app uses `eh-`;
+ * `eufyhome-` is the prefix of its QA environment only.
+ */
+export declare const TUYA_USERNAME_PREFIX = "eh-";
 /** AES-128-CBC key used to derive the Tuya password (16 bytes). */
 export declare const TUYA_PASSWORD_KEY: Buffer<ArrayBuffer>;
 /** AES-128-CBC IV used to derive the Tuya password (16 bytes). */
 export declare const TUYA_PASSWORD_IV: Buffer<ArrayBuffer>;
-/** The Tuya username for a eufy user id (`"eufyhome-" + eufyUserId`). */
+/** The Tuya username for a eufy user id (`"eh-" + eufyUserId`). */
 export declare function tuyaUsername(eufyUserId: string): string;
 /**
  * Derive the Tuya password for a eufy user id:
- * `UPPERCASE-HEX( AES-128-CBC-NoPadding( pad16("eufyhome-"+eufyUserId), KEY, IV ) )`.
+ * `UPPERCASE-HEX( AES-128-CBC-NoPadding( pad16("eh-"+eufyUserId), KEY, IV ) )`.
  * Deterministic (fixed KEY/IV) — the same user id always yields the same password.
  */
 export declare function deriveTuyaPassword(eufyUserId: string): string;
@@ -29,7 +32,7 @@ export declare function isoToDialCode(iso: string): string | undefined;
 export declare function resolveCountryCode(phoneCode?: string, region?: string, isoCode?: string): string;
 /** A derived Tuya login identity — everything needed to call the uid token/password login actions. */
 export interface TuyaAccount {
-    /** `"eufyhome-" + eufyUserId`. */
+    /** `"eh-" + eufyUserId`. */
     username: string;
     /** AES-derived password (uppercase hex). See {@link deriveTuyaPassword}. */
     password: string;

package/dist/transport/tuya/client.d.ts

@@ -50,8 +50,21 @@ export declare class TuyaClient {
      * Requires a working signer (the sign step).
      */
     buildRequest(action: TuyaAction): Record<string, string>;
-    /** Build + POST an action, returning the parsed envelope. Requires a working signer. */
+    /**
+     * Build + POST an action, returning the parsed envelope. Requires a working signer.
+     *
+     * On an `et=3` reply the envelope's `result` is a base64 AES-128-GCM blob, not an object; this
+     * decrypts it (keyed off the request's `requestId` and the session's `ecode`) and returns the
+     * decrypted inner envelope, so callers read `result` as an object regardless. A non-string `result`
+     * (an error, or an already-plain reply) passes through untouched.
+     */
     call<T = unknown>(action: TuyaAction): Promise<TuyaEnvelope<T>>;
+    /**
+     * Decode an et=3 reply. When `result` is a non-empty string it is the encrypted blob: decrypt and
+     * parse it (a wrong key or tampered blob fails the GCM tag in {@link decryptReply} and throws). The
+     * plaintext is itself the standard `{success, t, result}` envelope, which becomes the returned one.
+     */
+    private decodeReply;
     /**
      * Log into the Tuya cloud from a eufy user id (wire-confirmed from the eufy Security app).
      *
@@ -68,12 +81,13 @@ export declare class TuyaClient {
      */
     login(eufyUserId: string, phoneCode?: string): Promise<TuyaLoginResult>;
     /**
-     * READ/dump a device's cached data-points (`thing.m.device.cache.dp.get`).
-     * Builds the request without needing a working signer; the signer is only exercised on send.
+     * READ a device's current data-points (`smartlife.m.device.dp.get`). The envelope's `result` is a
+     * flat `{ "<dpId>": value }` map. Builds the request without needing a working signer; the signer is
+     * only exercised on send.
      */
-    getDeviceDps<T = unknown>(devId: string, dpCacheType?: number): Promise<TuyaEnvelope<T>>;
+    getDeviceDps<T = unknown>(devId: string): Promise<TuyaEnvelope<T>>;
     /**
-     * CONTROL: publish data-points to a device (`thing.m.device.dp.publish`). `dps` is
+     * CONTROL: publish data-points to a device (`smartlife.m.device.dp.publish`). `dps` is
      * `{ "<dpId>": <value> }`. `gwId` is the gateway/parent id (equals `devId` for a standalone gw).
      *
      * ⚠️ UNVERIFIED write — refuses to send by default. The `dp.publish` param shape

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

@@ -32,9 +32,9 @@ export declare class TuyaCommandRouter {
     /** Promise that resolves once Tuya login has completed. Reset by {@link bind}. */
     private loginOnce;
     /**
-     * eufy SN → Tuya device ids, populated by the facade via {@link registerDevice}.
-     * The facade extracts the Tuya id from the `raw` device record fields (`tuya_uuid`,
-     * `tuya_virtual_id`, `tuya_device_id`, `virtualId`) and registers it once the device list loads.
+     * eufy SN → Tuya device ids, populated via {@link registerDevice} once the device list loads.
+     * The Tuya id is the record's first non-empty `tuya_uuid` / `tuya_virtual_id` / `tuya_device_id` /
+     * `virtualId`, or the device's serial when the record carries none of them.
      */
     private readonly snMap;
     constructor(config?: TuyaCommandRouterConfig);
@@ -48,21 +48,17 @@ export declare class TuyaCommandRouter {
      */
     bind(userId: string, regionShard?: string, isoCode?: string): void;
     /**
-     * Register a eufy SN → Tuya devId mapping. Called by the facade for each `eufy_home_tuya`
-     * device after the cloud device list loads. The facade extracts the Tuya id from the device's
-     * raw record (`tuya_uuid` / `tuya_virtual_id` / `tuya_device_id` / `virtualId` fields).
-     * `gwId` defaults to `devId` — standalone devices share the two.
+     * Register a eufy SN → Tuya devId mapping for an `eufy_home_tuya` device. `devId` is the record's
+     * first non-empty `tuya_uuid` / `tuya_virtual_id` / `tuya_device_id` / `virtualId`, or the device's
+     * serial when the record carries none of them. `gwId` defaults to `devId` — standalone devices
+     * share the two.
      */
     registerDevice(sn: string, devId: string, gwId?: string): void;
     private ensureLoggedIn;
     /**
-     * Fetch a device's cached DPs from the Tuya cloud (`thing.m.device.cache.dp.get`) and deliver
-     * the raw DP map to the caller. Used for initial state hydration after MQTT subscribe — gets the
-     * last-known state without waiting for the first realtime push.
-     *
-     * The response shape from `getDeviceDps` is not yet pinned from a live capture. The defensive
-     * extraction tries both `result.dps` (a nested map) and bare `result` (a flat map), and returns
-     * `null` when neither yields a non-empty record.
+     * Read a device's current DPs from the Tuya cloud (`smartlife.m.device.dp.get`) and answer the DP
+     * map: the reply's flat `result`, kept to integer DP keys with scalar values. Answers `null` for an
+     * unregistered device, a failed reply, or a reply with no DPs.
      */
     fetchDps(sn: string): Promise<Record<string, unknown> | null>;
     /**

package/dist/transport/tuya/dp-codec.d.ts

@@ -1,14 +1,9 @@
 /**
- * Inbound Tuya DP event parsing and routing for eufy Home/Clean (`eufy_home_tuya`) devices.
+ * Inbound Tuya DP parsing and routing for eufy Home/Clean (`eufy_home_tuya`) devices.
  *
- * {@link parseTuyaDpReport} unwraps the Anker MQTT `{head, payload}` envelope and extracts the
- * raw DP map. {@link parseTuyaDpEvent} then validates and normalises it to a numeric-keyed record.
+ * {@link parseTuyaDpEvent} validates a Tuya cloud DP map and normalises it to a numeric-keyed record.
  * {@link TuyaDpRouter} delivers the result to the registered {@link TuyaDpInbound} listener so the
  * capability layer can consume Tuya state through the same typed getters as AIoT.
- *
- * Inbound messages arrive on `cmd/eufy_home/{model}/{sn}/res` with `sign_code: 0` (no additional
- * encryption — confirmed from clean-device captures). If a future capture shows `sign_code ≠ 0` the
- * payload will be AES-128-ECB encrypted with the device's localKey before the JSON can be parsed.
  */
 import type { TuyaDpInbound } from "../../core/contracts.js";
 /**
@@ -21,22 +16,6 @@ import type { TuyaDpInbound } from "../../core/contracts.js";
  * valid DP entry was found.
  */
 export declare function parseTuyaDpEvent(payload: unknown): Record<number, boolean | number | string> | null;
-/**
- * Extract a raw DP map from an inbound Anker MQTT message for a `eufy_home_tuya` device.
- *
- * Messages arrive in the same `{head, payload}` envelope the AIoT path uses, where `payload` is a
- * JSON **string**:
- * ```json
- * { "head": { "cmd": 65537, "cmd_status": 2, "sign_code": 0, ... },
- *   "payload": "{\"t\":\"…\",\"protocol\":2,\"data\":{\"104\":80,\"106\":0}}" }
- * ```
- * Two DP layouts inside the decoded payload are handled: Tuya-native (`data.dps`) and AIoT-direct
- * (`data` with integer-keyed DP ids). Falls back to flat `envelope.dps` / `envelope.data.dps`
- * shapes for any pre-parsed delivery. Returns `undefined` when no recognised shape is found.
- *
- * @internal
- */
-export declare function parseTuyaDpReport(raw: unknown): Record<string, unknown> | undefined;
 /**
  * Routes validated inbound Tuya DP events to the registered {@link TuyaDpInbound} listener.
  *

package/dist/transport/tuya/et3.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The per-request AES-128 key, `getEncryptoKey(requestId, ecode)`: take the lowercase hex of
+ * `HMAC-SHA256(key = requestId, msg = K[+ "_" + ecode])`, keep the first 16 hex characters, and use
+ * those characters as 16 ASCII bytes. `K` is the app HMAC key ({@link resolveSignKey}).
+ *
+ * `ecode` is the session's per-login encryption code (`User.ecode`, read from the decrypted
+ * `login.reg` reply). `ecode === null` selects the pre-session variant `msg = K` used to open the
+ * `token.get` and `login.reg` replies themselves, before any `ecode` is known.
+ */
+export declare function deriveBodyKey(requestId: string, ecode: string | null): Buffer;
+/**
+ * Encrypt an `et=3` request `postData`: AES-128-GCM under a random 12-byte nonce, laid out
+ * `nonce(12) ‖ ciphertext ‖ tag(16)` then base64 — the inverse of {@link decryptReply}, keyed by the
+ * same {@link deriveBodyKey}. No AAD. The request is signed over this blob.
+ */
+export declare function encryptBody(key: Buffer, json: string): string;
+/**
+ * Decrypt an `et=3` reply `result`: base64 → AES-128-GCM-decrypt-verify (`nonce = blob[0:12]`,
+ * `tag = blob[-16:]`, ciphertext between), gunzip when the plaintext is gzip-framed, and return the
+ * plaintext JSON string. Throws when the blob is too short or the GCM tag fails to authenticate.
+ */
+export declare function decryptReply(key: Buffer, resultB64: string): string;

package/dist/transport/tuya/request.d.ts

@@ -2,9 +2,10 @@
  * Tuya / Thingclips `api.json` request assembly + transport.
  *
  * Every call is a single `POST https://a1.tuyaeu.com/api.json` (EU) whose body is
- * **form-urlencoded plaintext params** (NOT an encrypted blob) plus a `sign`. This module builds
- * that param map for a given action, form-encodes it, POSTs it, and parses Tuya's response
- * envelope. The one non-plaintext piece — the `sign` digest — is delegated to a {@link TuyaSigner}.
+ * **form-urlencoded params** plus a `sign`. Under `et=3` the `postData` param is an AES-128-GCM blob
+ * and the reply `result` is encrypted the same way, with the same per-request key. This module builds
+ * that param map for a given action, form-encodes it, POSTs it, and parses Tuya's response envelope.
+ * The `sign` digest is delegated to a {@link TuyaSigner}.
  */
 /** Injectable POST transport — takes (url, form-body), returns the parsed JSON envelope. Native `fetch` by default. */
 export type TuyaHttpPost = (url: string, body: string) => Promise<unknown>;
@@ -24,7 +25,10 @@ export declare const TUYA_SDK_VERSION = "7.5.0";
 export declare const TUYA_APP_VERSION = "6.0.51_26722";
 /** A single action to call: the `a` (action) + `v` (version) + optional pre-serialized `postData`. */
 export interface TuyaAction {
-    /** Action name, e.g. `thing.m.device.dp.publish`. */
+    /**
+     * Action name as it goes on the wire, e.g. `smartlife.m.device.dp.publish`. The vendor SDK names
+     * its actions `thing.*` and rewrites a leading `thing` to `smartlife` before sending.
+     */
     a: string;
     /** Per-action version, e.g. `"1.0"` / `"2.0"`. */
     v: string;
@@ -43,6 +47,11 @@ export interface TuyaSession {
      * `"7cbfe6d8"` for this app's appId. Hardcode it.
      */
     chKey: string;
+    /**
+     * Per-login encryption code (`User.ecode`), read from the decrypted `login.reg` reply. Absent until
+     * login completes; it keys et=3 body encryption and reply decryption for every session call.
+     */
+    ecode?: string;
 }
 /**
  * The constant / environment fields of a request. All are plaintext and (except the sign-relevant
@@ -127,14 +136,14 @@ export interface SendOptions {
 export declare function sendApiRequest<T = unknown>(params: Record<string, string>, opts?: SendOptions): Promise<TuyaEnvelope<T>>;
 /**
  * CONTROL: publish device data-points. `dps` is `{ "<dpId>": <value> }`; note it is JSON-stringified
- * INSIDE the postData (Tuya nests the dps map as a string). Action `thing.m.device.dp.publish` v2.0.
+ * INSIDE the postData (Tuya nests the dps map as a string). Action `smartlife.m.device.dp.publish` v2.0.
  */
 export declare function buildPublishDpsAction(devId: string, gwId: string, dps: Record<string, unknown>): TuyaAction;
 /**
- * READ/dump: fetch a device's cached data-points. Action `thing.m.device.cache.dp.get` v2.0.
- * TODO(verify): `dpCacheType` default (1) was not pinned from the capture.
+ * READ: a device's current data-points. Action `smartlife.m.device.dp.get` v1.0, postData `{ devId }`.
+ * The reply `result` is a flat `{ "<dpId>": value }` map.
  */
-export declare function buildGetDeviceDpsAction(devId: string, dpCacheType?: number): TuyaAction;
+export declare function buildGetDeviceDpsAction(devId: string): TuyaAction;
 /**
  * LOGIN step 1: fetch a pre-login RSA token for a Tuya uid.
  * Wire-confirmed from the eufy Security app (`com.oceanwing.battery.cam`):
@@ -146,6 +155,7 @@ export declare function buildUsernameTokenGetAction(countryCode: string, usernam
  * LOGIN step 2: uid password login + auto-register.
  * Wire-confirmed from the eufy Security app: wire action
  * `smartlife.m.user.uid.password.login.reg`, v=1.0. `passwd` = hex of RSA-PKCS1-encrypt(MD5hex(aesPassword)).
+ * `options` is the JSON string `{"group": 1}`, as the app sends it.
  * On success returns `{ sid, uid }`.
  */
 export declare function buildPasswordLoginRegAction(countryCode: string, uid: string, passwd: string, token: string): TuyaAction;

package/dist/transport/tuya/sign.d.ts

@@ -44,6 +44,13 @@ export declare class StubSigner implements TuyaSigner {
  * The env var `TUYA_SIGN_KEY` can override this for non-standard builds.
  */
 export declare const TUYA_SIGN_K: string;
+/**
+ * Resolve the app-wide HMAC key {@link TUYA_SIGN_K}: an explicit `override` wins, then the
+ * `TUYA_SIGN_KEY` env var (for custom builds), then the built-in constant. Shared by the request
+ * signer ({@link HmacSigner}) and the et=3 body-key derivation, which key off the same `K`.
+ * @internal
+ */
+export declare function resolveSignKey(override?: string): string;
 /**
  * The real {@link TuyaSigner}: `sign = HMAC-SHA256(K, preimage)` as lowercase hex.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mega-yfue/eufy-sdk",
-  "version": "0.5.0-beta.9",
+  "version": "0.5.0-beta.90",
   "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",
@@ -73,14 +73,15 @@
   },
   "dependencies": {
     "jpeg-js": "^0.4.4",
-    "mqtt": "^5.16.0",
-    "protobufjs": "^8.8.0"
+    "mqtt": "^5.16.1",
+    "node-datachannel": "^0.33.4",
+    "protobufjs": "^8.8.1"
   },
   "devDependencies": {
-    "@types/node": "^26.6.3",
+    "@types/node": "^26.6.5",
     "esbuild": "^0.28.2",
-    "prettier": "^3.9.9",
+    "prettier": "^3.9.10",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.2"
+    "vitest": "^5.0.5"
   }
 }