@mega-yfue/eufy-sdk 0.2.0-beta.2 → 0.2.0-beta.21

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?: {
@@ -393,9 +393,9 @@ export declare class EufyMega extends EventEmitter {
     /**
      * Combine explicit P2P media with the optional passive push-thumbnail provider.
      *
-     * The retained still also becomes the answer for a live still that could not be captured. A station
-     * serves one camera at a time and a live view outranks a tile, so a still asked for while a sibling is
-     * being watched is refused at the transport. Answering the retained bytes answers the read rather than
+     * The retained still also becomes the answer for a live still that could not be captured. One session
+     * serves one camera at a time and a live view outranks a tile — a still does not open a connection of its
+     * own — so a still asked for while a sibling is being watched is refused at the transport. Answering the retained bytes answers the read rather than
      * failing it, marked {@link MediaProvider.snapshotLive} `retained` so the caller knows they are not
      * current. With nothing retained the refusal stands.
      */
@@ -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"));
      * ```
      */
@@ -752,10 +752,15 @@ export declare class EufyMega extends EventEmitter {
      */
     private sendRealtimeInit;
     /**
-     * Stations with a live P2P session. P2P is auto-managed: wired stations are warmed at login, battery
+     * The open P2P sessions, by key. P2P is auto-managed: wired stations are warmed at login, battery
      * stations open on demand (command / stream, or an opted-in event pre-warm) and idle-detach — so this
-     * map grows and shrinks over time. `p2pConnect(stationSn)` / `p2pClose(stationSn)` events track the
-     * changes.
+     * map grows and shrinks over time.
+     *
+     * A station's own session is keyed by its serial, and `p2pConnect(stationSn)` / `p2pClose(stationSn)`
+     * track those. A station serving more than one camera at once also holds a session per extra camera,
+     * keyed `<stationSn>#live:<channel>` — these carry media alone and raise no connection events, because
+     * a station announces its state to every client that connects and reporting each copy would double
+     * every event the station's own session already delivers.
      */
     getP2pSessions(): Map<string, P2PSession>;
     /**

package/dist/client/types.d.ts

@@ -5,7 +5,7 @@
  * `interface EufyMega` (the typed on/once/off/emit overloads) stays in `eufy-mega.ts` next to the
  * class — TS declaration merging requires both in the same module.
  */
-import type { MegaClientConfig } from "../transport/http/mega-client.js";
+import type { MegaClientConfig, SessionExpiredError } from "../transport/http/mega-client.js";
 import type { FcmStore } from "../transport/push/store.js";
 import type { FfmpegLevel } from "../transport/ffmpeg.js";
 import type { DeviceEventMap } from "../model/capabilities/index.js";
@@ -375,8 +375,12 @@ export type EufyMegaEventMap = {
      * token expired. The SDK has already cleared the persisted session, so recovery is a fresh `login()`
      * (which usually needs 2FA). Distinct from `error`: a session error is emitted ONLY here, not also
      * on `error`.
+     *
+     * The error carries the rate: `err.retryAfterMs` is how long the next session replacement is barred
+     * for, and `err.contended` says this session is being displaced by another client rather than expiring
+     * — which a re-login does not answer. A login made before that wait elapses extends it.
      */
-    sessionExpired: [err: Error];
+    sessionExpired: [err: SessionExpiredError];
     error: [err: Error];
 };
 /** Event names {@link EufyMega} can emit. */

package/dist/core/contracts.d.ts

@@ -75,28 +75,57 @@ export declare class CameraDisabledError extends Error {
     });
 }
 /**
- * A live stream was refused: the station is already serving another of its cameras to a viewer.
+ * Work on a station was refused: the station did not provide the session key that work requires.
  *
- * A station fans several cameras out over one session and serves ONE of them at a time. Accepting a second
- * live pull does not make it serve two: measured on a base carrying three attached cameras, each opened
- * stream took the station from the others in turn and all three received their media in bursts. So a second
- * viewer is refused rather than admitted and degraded, which is the difference between a caller being told
- * the constraint and a caller watching every picture stutter.
+ * 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.
  *
- * Which camera deserves the station is the caller's decision, not the SDK's, so nothing is queued or
- * pre-empted here.
+ * 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.
  *
- * A still is not refused: it yields the station instead, and answers with the retained image where one is
- * held. Only pulls that deliver continuous media contend for a viewer's place.
+ * `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 StationBusyError extends Error {
-    /** The channel the station is already serving. */
-    readonly servingChannel: number;
-    /** Always true: the station is busy now, and stops being busy when the other stream is released. */
+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 channel the station is already serving. */
-    servingChannel: number, options?: {
+    /** 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;
     });
 }
@@ -684,8 +713,9 @@ export interface MediaProvider {
         /**
          * Present and `true` only when these bytes are the RETAINED still rather than a fresh capture.
          *
-         * A live still is refused while a sibling camera on the same station is being watched, because a
-         * station serves one camera at a time and the live view is the picture someone is looking at. Answering
+         * A live still is refused while a sibling camera on the same station is being watched, because one
+         * session serves one camera at a time, a still does not open a connection of its own, and the live view
+         * is the picture someone is looking at. Answering
          * the retained still there answers the call instead of failing it, and this says the bytes are not
          * current. Absent means freshly captured.
          */
@@ -694,18 +724,18 @@ export interface MediaProvider {
     /**
      * Open a managed live stream.
      *
-     * Several cameras behind one station may stream at the same time only where the station serves them at
-     * the same time. Where it serves one camera at a time, a second viewer is refused with
-     * {@link StationBusyError} rather than admitted and degraded: accepting it does not make the station
-     * serve two, it makes both stutter. Which camera deserves the station is the caller's decision, so
-     * nothing is queued or pre-empted. Each handle receives only the frames the station tagged for ITS
-     * camera.
+     * Several cameras behind one station stream at the same time, each over its own connection to it. One
+     * connection serves one camera — a station answers the most recent start on a session, so two cameras
+     * sharing one take it from each other in turn — so a camera asked for while its station is already
+     * serving another gets a connection of its own. Measured on a base carrying two attached cameras, one
+     * at 3840x2160: both held full frame rate at once. Each handle receives only the frames the station
+     * tagged for ITS camera.
      *
      * @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,115 @@
+/**
+ * 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 battery discharge-cutoff (minimum-SOC) preset, as returned by
+ * `SolixClient.getPowerCutoff()`. `output_cutoff_data` is the minimum state-of-charge percent the
+ * option enforces; `id` is what `setPowerCutoff()` takes; `is_selected` (1) marks the current one.
+ */
+export interface SolixPowerCutoffOption {
+    id: number;
+    output_cutoff_data: number;
+    is_selected?: number;
+    [k: string]: unknown;
+}
+/**
+ * The Solarbank's battery SOC-limit settings — the `param_data` block read from / written to
+ * `site/get_site_device_param` under `param_type "27"` (verified live on an AE103). All values are
+ * whole-percent integers. `chargeUpperLimit` caps charging (the app's "charge limit" / max SOC) and
+ * `dischargeLowerLimit` floors discharging (the "discharge limit" / minimum SOC — the same quantity the
+ * realtime `b5` telemetry blob reports). `backupReserve` (+ its switch) is the reserved-for-outage SOC;
+ * `socCalibrationEnable` is the periodic full-cycle calibration toggle. The wire keys are the
+ * snake_case form (`charge_upper_limit`, `discharge_lower_limit`, `backup_reserve`,
+ * `backup_reserve_switch`, `soc_calibration_enable`).
+ */
+export interface SolixSocParams {
+    chargeUpperLimit: number;
+    dischargeLowerLimit: number;
+    backupReserve: number;
+    backupReserveSwitch: number;
+    socCalibrationEnable: number;
+}
+/** 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;
+}
+/** One device's membership entry within a site, as carried by `get_site_list`'s `site_device_list`. */
+export interface SolixSiteDeviceEntry {
+    device_sn: string;
+    /** The device's product/model code (the site list names this field `device_model`). */
+    device_model: string;
+    device_name?: string;
+    /** Anker device-type discriminator (e.g. 3 = Solarbank/battery, 6 = smart meter). */
+    device_type?: number;
+    [k: string]: unknown;
+}
+/**
+ * A site ("system") record, as returned by `SolixClient.getSites()`. A site is the account's home
+ * energy system — the "My Home" the app shows — grouping the member devices ({@link site_device_list})
+ * that a {@link SolixSiteReader} resolves into a `SolixSite`. Extra vendor fields are preserved.
+ */
+export interface SolixSiteRecord {
+    site_id: string;
+    site_name?: string;
+    /** Anker's site-type discriminator (e.g. 20 for a Solarbank-anchored home system). */
+    power_site_type?: number;
+    site_device_list?: SolixSiteDeviceEntry[];
+    [k: string]: unknown;
+}
+/**
+ * One Solarbank/battery entry inside a site "scene" snapshot ({@link SolixSiteScene}). The scene mirrors
+ * the app's dashboard read: values arrive as STRINGS. Only the fields this SDK actually consumes are
+ * typed (chiefly `bat_temperature`, the realtime `ff09` push doesn't reliably carry); the index signature
+ * preserves the rest (`bat_charge_power`, `charging_status`, `load_port_*`, `function_switch`, …) verbatim.
+ */
+export interface SolixSceneSolarbank {
+    device_sn?: string;
+    device_pn?: string;
+    /** Battery pack temperature in °C (string on the wire). The scene is the reliable source for this. */
+    bat_temperature?: string | number;
+    /** State of charge, % (string on the wire). Cross-checks the `ff09` `0xa3` SOC. */
+    bat_soc?: string | number;
+    [k: string]: unknown;
+}
+/**
+ * A site "scene" snapshot from {@link SolixClient.getSiteScene} — the app's dashboard read. The
+ * battery detail lives under `solarbank_info.solarbank_list` (NOT a top-level list). Only the shape this
+ * SDK reads is typed; everything else (grid_info, home_load_power, function flags, …) is preserved by the
+ * index signature. This is a low-rate backstop, never the realtime telemetry source.
+ */
+export interface SolixSiteScene {
+    solarbank_info?: {
+        solarbank_list?: SolixSceneSolarbank[];
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}

package/dist/core/store.d.ts

@@ -5,6 +5,14 @@ import type { RegionShard } from "../transport/http/mega-client.js";
  */
 export interface PersistedSession {
     userId: string;
+    /**
+     * The eufy account's own `user_id` — the id the `gtoken` header is hashed from, which is not always the
+     * `ap_cloud_user_id` that `userId` prefers.
+     *
+     * Always written, equal to `userId` when the login reply carried only the one id. Absent therefore means a
+     * record from before this was tracked, which {@link isSessionValid} refuses rather than restore.
+     */
+    accountUserId?: string;
     authToken: string;
     geoKey?: string;
     region: RegionShard;
@@ -19,25 +27,45 @@ 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 persisted session is usable if it has a token that isn't (near-)expired. */
+/**
+ * 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 carries a complete credential — token, bound ECDH key, and the account
+ * id the `gtoken` header is hashed from — whose token isn't (near-)expired.
+ *
+ * `accountUserId` is part of the credential, not an optional extra: a record without it was written before
+ * that id was tracked, so it can only be restored as the other id, which is what the gateway rejects the
+ * header on. Nothing in a restored session can recover it either — the id arrives with a login reply. So such
+ * a record is refused and one login re-establishes it, rather than reinstating a session whose every
+ * authenticated call fails identically.
+ */
 export declare function isSessionValid(s: PersistedSession | null, skewSec?: number): boolean;