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

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"));
      * ```
      */

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;