@mega-yfue/eufy-sdk 0.2.0-beta.9 → 0.2.0

package/dist/client/device-registry.d.ts

@@ -1,13 +1,3 @@
-/**
- * The station a device's traffic belongs to, from its cloud record and its own serial.
- *
- * `parent_sn` carries the parent on a HomeBase-attached device. `station_sn` is frequently absent there —
- * empty on every attached sensor of a T8010 — and serves only as a fallback. An empty string states no
- * station.
- *
- * A device naming no parent answers its own serial, so every device has a station.
- */
-export declare function resolvedStationSn(raw: Record<string, unknown>, sn: string): string;
 /**
  * DeviceRegistry — the device list/record/capability-resolution collaborator behind {@link EufyMega}.
  *
@@ -85,6 +75,9 @@ export declare class DeviceRegistry {
     private devices;
     /** Per-(station, channel) capability cache for {@link capabilitiesForFrame}; `null` = negative hit. */
     private readonly frameCapsCache;
+    /** {@link stationChannels} of {@link channelMapFor}, the roster it was computed over. */
+    private channelMap;
+    private channelMapFor?;
     /**
      * Serials whose per-device param overlay has been refused. The call is owner-gated, so on a shared or
      * member account it fails for the whole life of the client — retrying it every refresh spends a request
@@ -291,33 +284,26 @@ export declare class DeviceRegistry {
      * hub would emit indistinguishable events. The facade enriches the payload with this.
      */
     serialForFrame(stationSn: string, channel: number): string | undefined;
-    /**
-     * The parent station a device's frames arrive under.
-     *
-     * `parent_sn` on the cloud record is the field that is actually populated for a HomeBase-attached
-     * device — `stationSn` is frequently absent (observed empty on every attached sensor of a T8010),
-     * so keying on it alone silently resolves an attached device to ITSELF and no frame ever matches.
-     * Mirrors the router's own session-keying precedence, which is the source of truth for which
-     * station a device's traffic belongs to. Answering the device's OWN serial is what "stands alone"
-     * means, so this is also the topology signal `record()`/`capsOf` hand the resolver.
-     */
-    private stationOf;
     /**
      * The device a `(station, channel)` pair refers to — a station fans out to attached devices by
      * `device_channel`, while a standalone device is its own station at channel 0.
      *
-     * A device claims a channel only when its record actually STATES one. Treating a missing
-     * `device_channel` as 0 turns every such device into a rival claimant for channel 0, where a
-     * station legitimately has an attached device already, and the winner is then decided by cloud list
-     * order — so the same frame resolves to different devices across refreshes. The resolved serial now
-     * decides where realtime state is written, not just which decoders may run, so an ambiguous answer
+     * A device claims a channel only when its record actually STATES one that no other device attached to
+     * the same station also states ({@link stationChannels}). Treating a missing `device_channel` as 0, or
+     * letting two claimants of one channel both hold it, leaves the winner to cloud list order — which a
+     * partial refresh reorders — so the same frame resolves to different devices across refreshes. The resolved
+     * serial decides where realtime state is written, not just which decoders may run, so an ambiguous answer
      * writes one device's params onto another.
      *
      * An attached device that names the channel wins over the station itself, which is what a station
-     * fanning traffic out by channel means; the station answers for channel 0 only when nothing is
-     * attached there, which is also the standalone case (a device is its own station).
+     * fanning traffic out by channel means. A channel two attached devices both state belongs to one of them,
+     * which cannot be told apart, so it answers nothing rather than the station. The station answers for
+     * channel 0 only when nothing attached states it, which is also the standalone case (a device is its own
+     * station).
      */
     private deviceForFrame;
+    /** {@link stationChannels} over the current roster, recomputed only when the roster itself is replaced. */
+    private stationChannelMap;
     /**
      * Resolve the capability set of the device a P2P frame belongs to — the `(station, channel)` pair
      * (a station fans out to attached devices by `device_channel`; a standalone device is its own

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

@@ -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.
      */
@@ -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

@@ -130,28 +130,23 @@ export declare class StationUnreachableError extends Error {
     });
 }
 /**
- * A live stream was refused: the station is already serving another of its cameras to a viewer.
+ * Work on a device was refused: its channel within its station cannot be established from the device records.
  *
- * 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.
- *
- * Which camera deserves the station is the caller's decision, not the SDK's, so nothing is queued or
- * pre-empted here.
- *
- * 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.
+ * A device attached to a HomeBase is addressed by a channel within that station: a media start and every
+ * per-channel command name it. When its record states no channel, or another device attached to the same station
+ * states the same one, any channel chosen would address whichever device actually holds it (streaming another
+ * camera's video under this serial), so nothing is sent. The `station-channel-unresolved` trace says which.
  */
-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. */
-    readonly retryable = true;
+export declare class DeviceChannelUnresolvedError extends Error {
+    /** The device that could not be addressed. */
+    readonly sn: string;
+    /** The station it is attached to. */
+    readonly stationSn: string;
     constructor(
-    /** The channel the station is already serving. */
-    servingChannel: number, options?: {
+    /** The device that could not be addressed. */
+    sn: string, 
+    /** The station it is attached to. */
+    stationSn: string, options?: {
         cause?: unknown;
     });
 }
@@ -739,8 +734,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.
          */
@@ -749,12 +745,12 @@ 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

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/solix-types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * 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;
+    /**
+     * Number of ATTACHED expansion battery packs — the built-in battery is the host, not a pack. Read as
+     * `expansionPacks`. Observed live as `0` on a standalone AE103 main unit; a populated value (and the
+     * matching per-pack `bms_list` detail) has not yet been captured with a pack attached.
+     */
+    sub_package_num?: 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;