@mega-yfue/eufy-sdk 0.2.0-beta.0 → 0.2.0-beta.10

package/README.md

@@ -23,11 +23,6 @@
 
 ---
 
-> [!IMPORTANT]
-> **Not usable yet.** This repository is being set up: the scaffold, the CI gate and the docs pipeline
-> are in place, the library source lands next. `0.0.1` exists on npm only to prove the release
-> pipeline works — it is an empty package. Wait for `0.1.0`.
-
 ## What it is
 
 A TypeScript SDK for the Anker eufy cloud that the current eufy app speaks. It logs in (captcha and 2FA
@@ -37,14 +32,18 @@ you drive through a **typed, fluent API**:
 ```ts
 const dev = await eufy.getDevice(sn);
 
-const stored = await dev.camera()?.snapshotStored?.(); // latest retained push JPEG
-const fresh = await dev.camera()?.snapshotLive(); // explicit fresh live capture
-await dev.panTilt()?.rotate(PtzDirection.left);
-await dev.light()?.setBrightness(60);
+const stored = await dev.camera?.()?.snapshotStored?.(); // latest retained push JPEG
+const fresh = await dev.camera?.()?.snapshotLive?.(); // explicit fresh live capture
+await dev.ptz?.()?.rotate(PtzDirection.left);
+await dev.light?.()?.setBrightness(60);
 
-eufy.on("motion", (e) => console.log(e.device.name, "saw something"));
+eufy.on("motion", (e) => console.log(e.deviceSn, "saw something"));
 ```
 
+Accessors and methods are optional because both are **evidence-gated**: a device exposes exactly the
+features it reported, so the optionality states that one may be absent. An **unverified write path
+throws** rather than send a frame it cannot stand behind.
+
 Realtime arrives over **P2P** (cameras and HomeBases), **secure MQTT** (appliances) and **push**
 (events), all surfaced as typed semantic events. Live **video streaming** works, with one shared pull
 fanned out to every consumer.
@@ -56,12 +55,10 @@ code path and an unlisted or future device resolves the same way as a known one.
 ## Install
 
 ```bash
-npm install @mega-yfue/eufy-sdk
+npm install @mega-yfue/eufy-sdk         # latest stable
+npm install @mega-yfue/eufy-sdk@beta    # the prerelease of the version in review
 ```
 
-Releases go to **npmjs**, published from CI with provenance. Prereleases ship on the `beta` channel
-(`npm install @mega-yfue/eufy-sdk@beta`) while a version is still under review.
-
 **Node.js ≥ 24.5.0** is required, not just recommended (see [`.nvmrc`](./.nvmrc)). `ffmpeg` is
 optional — only the live JPEG snapshot and one-shot mp4 record paths use it,
 and a host that ships its own build names it with `new EufyMega({ ffmpegPath })` rather than needing
@@ -69,34 +66,13 @@ one on `PATH`.
 
 ## Documentation
 
-The guides at **<https://mega-yfue.github.io/>** are the source of truth; this README stays a thin
-landing page. They cover installing and logging in, devices and capabilities, events and realtime
-transports, consuming live media, and the generated API reference. Runnable, typechecked samples live
-in [`examples/`](./examples/).
-
-## Design
-
-Four layers, one dependency direction — `core` → `transport` → `model` → `client`:
-
-```
-src/
-  core/         shared floor: crypto, cross-layer contracts, value types, session store
-  transport/    every byte-on-a-wire module: http, mqtt, p2p, push, tuya
-  model/        Device + one self-contained module per capability
-  client/       the facade: login, device registry, event fan-out
-  index.ts      public surface — one `export *` per layer barrel
-```
-
-**Capability ↔ transport decorrelation is a hard, CI-enforced rule:** `model/` never imports
-`transport/` and vice versa. A capability describes what a value MEANS; a transport moves bytes and
-never names a feature. Anything genuinely shared is a contract in `core/`. That rule and the rest of
-the code practice are in [AGENTS.md](./AGENTS.md).
-
-Three runtime dependencies — `mqtt`, `protobufjs`, `jpeg-js` — and that is deliberate. HTTP is native
-`fetch`, hashing and ciphers are `node:crypto`, 64-bit integers are `BigInt`.
+The guides at **<https://mega-yfue.github.io/>** cover installing and logging in, devices and
+capabilities, events and realtime transports, consuming live media, and the generated API reference.
+Runnable, typechecked samples live in [`examples/`](./examples/).
 
-**Unverified write paths throw rather than guess.** Some writes are fire-and-forget, so a guessed
-frame looks exactly like success; the SDK refuses instead of pretending.
+The architecture — four layers with one dependency direction, and the CI-enforced rule that keeps
+capabilities and transports from importing each other — is in [AGENTS.md](./AGENTS.md), with the rest of
+the code practice.
 
 ## Develop
 

package/dist/client/eufy-mega.d.ts

@@ -4,11 +4,11 @@
  * Cloud APIs:  the eufy v6 cloud (+ legacy, planned)
  * Realtime:    secure MQTT (appliances)  +  P2P (cameras/HomeBases)
  *
- *   const eufy = new EufyMega({ email, password, region: "eu" });
+ *   const eufy = new EufyMega({ email, password, region: "eu-pr" });
  *   await eufy.login(); // → LoginResult; on success the SDK auto-starts realtime (push/MQTT/wired P2P)
  *   eufy.on("motion", (e) => console.log(e.deviceSn)); // typed semantic events — flowing already
  *   const dev = await eufy.getDevice((await eufy.getDevices())[0].sn);
- *   await dev.camera()?.snapshotStored();
+ *   await dev.camera?.()?.snapshotStored?.();
  *
  * Connectivity is SDK-managed: the host calls no `connect*`. P2P to a battery camera is opened only
  * when a command/stream/doorbell-ring needs it and closed when idle, so the camera can sleep.
@@ -346,8 +346,8 @@ export declare class EufyMega extends EventEmitter {
      * @example
      * ```ts
      * const res = await eufy.login();
-     * if (res.status === "captcha") await eufy.solveCaptcha(await ask(res.image));
-     * else if (res.status === "2fa") await eufy.submitVerifyCode(await ask());
+     * if (res.status === "captcha") await eufy.solveCaptcha(await promptUser(res.image));
+     * else if (res.status === "2fa") await eufy.submitVerifyCode(await promptUser());
      * ```
      */
     login(opts?: {
@@ -493,7 +493,7 @@ export declare class EufyMega extends EventEmitter {
      * @example
      * ```ts
      * const dev = await eufy.getDevice(sn);
-     * if (dev.has("camera")) await dev.camera()?.snapshotStored();
+     * if (dev.has("camera")) await dev.camera?.()?.snapshotStored?.();
      * console.log(dev.getProperty("battery"));
      * ```
      */
@@ -707,11 +707,38 @@ export declare class EufyMega extends EventEmitter {
      * {@link ensureMqttStarted} owns installing it, subscribing devices, and the epoch check, so that
      * lifecycle lives in exactly one place. Only ever called through {@link ensureMqttStarted}.
      *
+     * Identified by a client id built from this client's `openudid`, not by the certificate's name:
+     * that name is `{user_id}-{app_name}`, which every client on the account shares per line, and a
+     * duplicate client id is a takeover the broker resolves by evicting the incumbent. The id shape is
+     * the app's own (`android-{app_name}-{uid}-{uuid}-{ts}`, see {@link buildAppShapedClientId}), which
+     * the broker grants on the `eufy_security` credential.
+     *
+     * It separates two clients exactly as far as their `openudid` does: a caller that supplies none
+     * gets the value derived from the account, which every such client shares — the same condition
+     * under which their logins already displace each other (`MegaClientConfig.openudid`).
+     *
+     * A client id the broker REFUSES falls back to the certificate's name, since a shared channel beats
+     * none, and that transport then keeps that name until {@link disconnect}. Only a refusal: a connect
+     * that fails for any other reason rejects the bring-up, which clears its memo in
+     * {@link ensureMqttStarted} so the next one asks under this client's own id again — a dropped
+     * socket must not be what moves a process onto the shared name for good.
+     */
+    private startMqtt;
+    /**
+     * Connect one secure-MQTT transport under `clientId`, or under the certificate's own name when it is
+     * omitted, and wire its decode and fan-out. See {@link startMqtt} for which id is used and why.
+     *
+     * The fan-out is wired once the connection stands, so an attempt that is discarded — a client id the
+     * broker refuses, a socket that dies mid-handshake — never reports a connection a consumer never had;
+     * the connect it just completed is announced here instead. Errors raised while connecting are held
+     * only to keep an emitter without an `error` listener from throwing, and are reported once the
+     * transport is one a consumer owns.
+     *
      * The inbound decode is gated by the reporting device's own capabilities, so one line's decoder never
      * runs against another's traffic, and the DP frame is unwrapped here — the layer that may import the
      * transport — so a capability reads tags without owning any framing.
      */
-    private startMqtt;
+    private connectMqtt;
     /**
      * Subscribe the devices on one credential scope; a failing subscribe is reported, not fatal (one
      * unreachable device must not stop the rest of the roster from coming up).

package/dist/core/contracts.d.ts

@@ -74,6 +74,61 @@ export declare class CameraDisabledError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * Work on a station was refused: the station did not provide the session key that work requires.
+ *
+ * A station reached over its HomeBase encrypts what it is sent under a key negotiated once per connection, and
+ * a media start for an attached camera has no unencrypted form at all — so without that key there is nothing
+ * to send, however reachable the station is. Naming this apart from a source that failed is what separates an
+ * account whose cipher material could not be resolved from a camera that is off, a station that is busy, or a
+ * stream that produced nothing: they share no next step.
+ *
+ * The `level2-unavailable` trace states WHY the key is not coming. This states only that it is not, because
+ * that is what the refusal itself knows.
+ *
+ * `stationSn` is the station that owed the key, which is the parent for an attached camera and therefore not
+ * the serial the refused call was made about: several cameras refused at once are one station's outcome, and
+ * nothing else in the refusal says so.
+ */
+export declare class StationKeyUnavailableError extends Error {
+    /** The station whose session key did not arrive. */
+    readonly stationSn: string;
+    /** Always true: the negotiation is per connection, so a later one may still produce a key. */
+    readonly retryable = true;
+    constructor(
+    /** The station whose session key did not arrive. */
+    stationSn: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Work on a station was refused: its session did not connect within the wait it was given.
+ *
+ * A station is reached over its own session, and nothing addressed to it — a media start, a property read, a
+ * still — can be attempted before that session is up. Naming this apart from every other failure is what tells
+ * a station that could not be reached at all from one that answered and then refused, or one that served media
+ * a caller could not use: those call for opposite next steps, and a caller cannot infer which it had from a
+ * message.
+ *
+ * `waitedMs` is how long was actually waited, which a caller compares against its own deadline to know whether
+ * this SDK concluded or its own bound expired first. `stationSn` is the station that could not be reached —
+ * the parent for an attached camera, so it is not derivable from the serial the call was made about.
+ */
+export declare class StationUnreachableError extends Error {
+    /** The station whose session did not connect. */
+    readonly stationSn: string;
+    /** How long the session was waited on before this was raised. */
+    readonly waitedMs: number;
+    /** Always true: a station unreachable now may answer on a later attempt. */
+    readonly retryable = true;
+    constructor(
+    /** The station whose session did not connect. */
+    stationSn: string, 
+    /** How long the session was waited on before this was raised. */
+    waitedMs: number, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * A live stream was refused: the station is already serving another of its cameras to a viewer.
  *
@@ -703,9 +758,9 @@ export interface MediaProvider {
      *
      * @example
      * ```ts
-     * const stream = await cam.live();
-     * stream.on("video", (frame) => write(frame.data)); // Annex-B
-     * stream.stop(); // detach this consumer
+     * const stream = await cam.live?.();
+     * stream?.on("video", (frame) => sink.write(frame.data)); // Annex-B
+     * stream?.stop(); // detach this consumer
      * ```
      */
     live(opts?: SharedSourceHints & AbortableCall & Record<string, unknown>): Promise<LiveStreamConsumer>;

package/dist/core/crypto.d.ts

@@ -35,6 +35,14 @@ export declare const EUFY_MEGA_LOCAL_KEY_HEX = "2500a7d5617812f9d52515b2c8f20a3d
  * the mega localKey. Identified by HMAC-matching a captured eufylife key-exchange signature.
  */
 export declare const EUFYLIFE_LOCAL_KEY_HEX = "118c12c81e211149304bd70a0c071d01";
+/**
+ * The **Anker Solix** passport localKey — the AES-128 bootstrap key for the `anker_power` app-line
+ * (power stations / smart meter). Solix runs the SAME `algo_ecdh` passport as the eufy_mega stack,
+ * re-skinned under a different `app-name` + API host, so the login key-exchange wraps the ephemeral
+ * client public key with this key; distinct from {@link EUFY_MEGA_LOCAL_KEY_HEX}. Authenticated Solix
+ * reads carry only the token + `gtoken` (no per-request encryption).
+ */
+export declare const SOLIX_LOCAL_KEY_HEX = "e8ad18f61bbd3fbd52d5ed12d14d3b9c";
 /**
  * Hardcoded server P-256 public key (uncompressed 0x04||X||Y) used to encrypt
  * the LOGIN password via a one-shot ECDH (separate from the per-session key).
@@ -44,6 +52,8 @@ export declare const SERVER_STATIC_PUBLIC_KEY_HEX = "04c5c00c4f8d1197cc7c3167c52
 export declare function genId(): string;
 /** Unix seconds as a string (X-Request-Ts). */
 export declare function nowSec(): string;
+/** md5 hex digest — the one place this derivation lives (gtoken, openudid seeds, …). */
+export declare function md5Hex(input: string): string;
 /** gtoken header = md5(user_id) hex. */
 export declare function gtoken(userId: string): string;
 /** 16-byte AES key = first half of the shared secret hex (shareKey[:16 bytes]). */

package/dist/core/index.d.ts

@@ -5,5 +5,6 @@ export * from "./raw-dp-writer.js";
 export * from "./raw-dp-hex.js";
 export * from "./logger.js";
 export * from "./store.js";
+export * from "./solix-types.js";
 export * from "./util.js";
 export * from "./lz4-block.js";

package/dist/core/logger.d.ts

@@ -19,7 +19,9 @@ export type LogLevel = "debug" | "info" | "warn" | "error";
  * ```ts
  * // A custom sink (or pass a tslog / winston instance directly — they already match this shape):
  * const eufy = new EufyMega({
- *   logger: { debug: (m, ...a) => log.debug(m, ...a), info: () => {}, warn: console.warn, error: console.error },
+ *   email,
+ *   password,
+ *   logger: { debug: (m, ...a) => myLog.debug(m, ...a), info: () => {}, warn: console.warn, error: console.error },
  * });
  * ```
  */
@@ -38,8 +40,8 @@ export declare const noopLogger: Logger;
  *
  * @example
  * ```ts
- * const eufy = new EufyMega({ logger: new ConsoleLogger() });        // verbose
- * const quiet = new EufyMega({ logger: new ConsoleLogger("warn") }); // warn + error only
+ * const eufy = new EufyMega({ email, password, logger: new ConsoleLogger() });        // verbose
+ * const quiet = new EufyMega({ email, password, logger: new ConsoleLogger("warn") }); // warn + error only
  * ```
  */
 export declare class ConsoleLogger implements Logger {

package/dist/core/solix-types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Anker Solix vendor-JSON record shapes — the cross-layer contract between the transport client (which
+ * RETURNS them off the wire) and the model layer (which resolves them into `SolixDevice`). They live in
+ * `core` for the same reason the command/media boundary does: the hard `transport ⊥ model` rule forbids
+ * either layer importing the other, so a type both need is neither's to own.
+ *
+ * @module core/solix-types
+ */
+/** A discovered Solix device record, as returned by `SolixClient.getDevices()`. */
+export interface SolixDeviceRecord {
+    device_sn: string;
+    product_code: string;
+    device_name?: string;
+    alias_name?: string;
+    device_sw_version?: string;
+    wifi_online?: boolean;
+    wifi_name?: string;
+    rssi?: string | number;
+    [k: string]: unknown;
+}
+/** One product in the pairable-product catalog. Extra vendor fields (images, guides) are preserved. */
+export interface SolixProduct {
+    /** SKU / model code, e.g. `A1782`. */
+    product_code: string;
+    /** Marketing name, e.g. `SOLIX F3000`. */
+    name: string;
+    /** Variant/sub-model codes under this product, when present. */
+    p_codes?: unknown[];
+    [k: string]: unknown;
+}
+/** A catalog category (e.g. "Portable Power Station") and its products. */
+export interface SolixProductCategory {
+    name: string;
+    products: SolixProduct[];
+    [k: string]: unknown;
+}

package/dist/core/store.d.ts

@@ -19,25 +19,36 @@ export interface PersistedSession {
     tokenExpiresAt: number;
     savedAt: number;
 }
-export interface SessionStore {
-    load(): PersistedSession | null;
-    save(s: PersistedSession): void;
+/**
+ * A place to persist a session record across runs. Parameterised on the record shape so other Anker
+ * lines (e.g. Solix, whose record is not a `PersistedSession`) can reuse the same file/memory
+ * stores rather than re-implementing them. Defaults to `PersistedSession` for the eufy path.
+ */
+export interface SessionStore<T = PersistedSession> {
+    load(): T | null;
+    save(s: T): void;
     clear(): void;
 }
 /** In-memory store (no persistence) — the default. */
-export declare class MemorySessionStore implements SessionStore {
+export declare class MemorySessionStore<T = PersistedSession> implements SessionStore<T> {
     private s;
-    load(): PersistedSession | null;
-    save(s: PersistedSession): void;
+    load(): T | null;
+    save(s: T): void;
     clear(): void;
 }
 /** JSON-file store, e.g. new FileSessionStore("./.eufy-session.json"). */
-export declare class FileSessionStore implements SessionStore {
+export declare class FileSessionStore<T = PersistedSession> implements SessionStore<T> {
     private readonly path;
     constructor(path: string);
-    load(): PersistedSession | null;
-    save(s: PersistedSession): void;
+    load(): T | null;
+    save(s: T): void;
     clear(): void;
 }
+/**
+ * A token is still usable if it has no known expiry, or expires more than `skewSec` from now. The one
+ * place the expiry/skew rule lives — reused by {@link isSessionValid} and by other lines' session checks
+ * (e.g. Solix) whose session shape differs but whose freshness rule is identical.
+ */
+export declare function tokenNotExpired(tokenExpiresAt: number | undefined, skewSec?: number): boolean;
 /** A persisted session is usable if it has a token that isn't (near-)expired. */
 export declare function isSessionValid(s: PersistedSession | null, skewSec?: number): boolean;