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

package/dist/model/solix-device.d.ts

@@ -0,0 +1,102 @@
+import { type SolixCapability, type SolixEnergyMeterReads } from "./capabilities/solix.js";
+import type { SolixDeviceRecord, SolixProductCategory } from "../core/solix-types.js";
+/**
+ * The device record shape, re-exported from the model surface. It lives in `core/solix-types` so the
+ * transport client can return it without crossing the transport↔model line.
+ */
+export type { SolixDeviceRecord } from "../core/solix-types.js";
+export interface SolixIdentity {
+    serial: string;
+    productCode: string;
+    /** Friendly name — the catalog marketing name if resolvable, else the record's alias/name. */
+    name: string;
+    /** Anker catalog category (e.g. "Accessory", "Portable Power Station"), if resolvable. */
+    category?: string;
+}
+export interface SolixConnectivity {
+    online: boolean;
+    rssi?: number;
+    ssid?: string;
+}
+/**
+ * The `dev.energyMeter()` handle: the members-derived reads ({@link SolixEnergyMeterReads} —
+ * `meterVoltageL1` is present only once a frame carrying its tag has landed). Every not-yet-named meter
+ * quantity is read from {@link SolixDevice.telemetry} under its `channel_<hex tag>` key instead, which a
+ * static members table cannot enumerate.
+ */
+export type SolixEnergyMeter = SolixEnergyMeterReads;
+/** Options for {@link SolixDevice}. */
+export interface SolixDeviceOptions {
+    /** Catalog categories (from `SolixClient.getProductCatalog()`) — used to resolve name + category. */
+    catalog?: SolixProductCategory[];
+}
+/**
+ * A discovered Solix device with resolved category + capabilities. Feed live telemetry with
+ * {@link applyReading} (from {@link SolixMqtt}'s `reading` events) to populate value accessors.
+ */
+export declare class SolixDevice {
+    readonly serial: string;
+    readonly productCode: string;
+    readonly record: SolixDeviceRecord;
+    private readonly caps;
+    private readonly identity_;
+    private values;
+    constructor(record: SolixDeviceRecord, opts?: SolixDeviceOptions);
+    /** All capabilities this device carries. */
+    get capabilities(): SolixCapability[];
+    /** Whether the device carries a capability — the only correct way to branch on behaviour. */
+    has(capability: SolixCapability): boolean;
+    /**
+     * Merge a live telemetry reading (a `SolixMqtt` `reading` event) so accessors reflect it. Takes the
+     * WHOLE reading, not just its values, and drops one addressed to a different device: the documented
+     * wiring is `mqtt.on("reading", r => device.applyReading(r))`, and one MQTT stream carries every
+     * watched meter on the account — so without this filter two meters would cross-feed each other's floats.
+     * A reading with no `deviceSn` (a hand-built one) is accepted as-is.
+     */
+    applyReading(reading: {
+        deviceSn?: string;
+        values: Record<string, number>;
+    }): void;
+    /** All decoded float telemetry channels from the latest applied reading (raw, `channel_<tag>` keys). */
+    telemetry(): Record<string, number>;
+    identity(): SolixIdentity;
+    firmware(): {
+        version: string;
+    } | undefined;
+    connectivity(): SolixConnectivity | undefined;
+    /**
+     * The members-derived `energyMeter` reads, or `undefined` when the device has no meter. Each getter is
+     * installed only for a tag this device has actually reported, and reads `this.values` LIVE — a handle
+     * held across an {@link applyReading} reflects the newer values. Getter INSTALLATION is fixed at the
+     * time of this call, so re-call it to pick up a tag first seen since.
+     */
+    energyMeter(): SolixEnergyMeter | undefined;
+    /**
+     * The {@link MemberDeps} the members engine needs: a read closure over the live values store, and the
+     * evidence gate (`ctx.paramIds`) rebuilt from the ff09 tags this device has reported. No `codec` — the
+     * codecs are eufy transport families and a Solix device belongs to none of them. The sink is a no-op:
+     * Solix telemetry is read-only, no member here dispatches a command.
+     */
+    private meterDeps;
+    /** The ff09 tags this device has reported, derived from the decoder's `channel_<hex>` keys. */
+    private seenTags;
+}
+/**
+ * The minimum a client must offer to be discovered against — the two wire reads {@link discoverSolixDevices}
+ * composes. Typed STRUCTURALLY (not as `SolixClient`) so the model layer never imports the transport
+ * client: the hard `transport ⊥ model` rule forbids it, and a structural shape needs no import.
+ */
+export interface SolixDeviceReader {
+    getDevices(): Promise<SolixDeviceRecord[]>;
+    getProductCatalog(): Promise<SolixProductCategory[]>;
+}
+/**
+ * Discover an account's Solix devices as capability-driven {@link SolixDevice} objects — the wire+model
+ * composition (a transport read + the product catalog) that used to be `SolixClient.discoverDevices()`.
+ * It lives in the model layer because it builds `SolixDevice`; the wire client (now `transport/http`)
+ * cannot, and passing it structurally keeps the layers decorrelated. Feed live telemetry to each result
+ * via `SolixDevice.applyReading`.
+ */
+export declare function discoverSolixDevices(client: SolixDeviceReader, opts?: {
+    catalog?: SolixProductCategory[];
+}): Promise<SolixDevice[]>;

package/dist/model/types.d.ts

@@ -28,10 +28,10 @@
  *
  * `display` is the T87Ax Smart Display line — its own codec because its `device_type` collides with
  * the security residual range (confirmed live, 2026-09-04: it connects over secure MQTT with no
- * `p2p_did`, never P2P). Its param namespace and product line are nonetheless grouped into `security`
- * by maintainer decision, not wire evidence — see {@link namespaceForCodec}. No capability module
- * targets it yet: no screen/audio/assistant param has been observed, only its own small cloud-param
- * namespace (ids 8001-8006).
+ * `p2p_did`, never P2P). It owns its own param namespace (ids 8001-8006) and its own product line, so
+ * no other line's capability can attach to it — see `namespaceForCodec` and `CODEC_LINE`. The `display`
+ * capability targets it and reads the charge; no screen/audio/assistant param has been observed, so
+ * those are absent rather than deferred.
  */
 export type Codec = "station" | "camera" | "sensor" | "lock" | "keypad" | "vacuum" | "mower" | "light" | "printer" | "display";
 /**
@@ -39,7 +39,7 @@ export type Codec = "station" | "camera" | "sensor" | "lock" | "keypad" | "vacuu
  * it maps to a {@link CapabilityModule} that owns its property schema. Extend this union as
  * new capabilities are modelled — adding one never requires a subclass.
  */
-export type Capability = "video" | "snapshot" | "motion" | "person_detection" | "battery" | "light" | "ptz" | "doorbell" | "contact" | "leak" | "smoke" | "co" | "siren" | "lock" | "keypad" | "arming" | "storage" | "rtsp" | "camera" | "audio" | "vacuum_clean" | "vacuum_dock" | "suction" | "locate" | "smart_light" | "info";
+export type Capability = "video" | "snapshot" | "motion" | "person_detection" | "battery" | "light" | "ptz" | "doorbell" | "contact" | "leak" | "smoke" | "co" | "siren" | "lock" | "keypad" | "arming" | "storage" | "rtsp" | "camera" | "audio" | "vacuum_clean" | "vacuum_dock" | "suction" | "locate" | "smart_light" | "display" | "info";
 /** Value type of a property. */
 export type PropertyValueType = "bool" | "number" | "string" | "enum";
 /**

package/dist/transport/ff09.d.ts

@@ -397,6 +397,13 @@ export interface Ff09SettingsResponse {
  * padding past the last real field.
  */
 export declare function parseFf09SettingsResponse(plain: Buffer): Ff09SettingsResponse;
+/**
+ * Walk a bounded `tag|len|value` TLV region into a `tag → bytes` map. Stops at a `0x00` tag (only ever
+ * trailing zero-padding, never a real field — real tags start at `0xa1`) and refuses a field whose
+ * declared length would overrun `end`, so a corrupt length can't read past the region (e.g. into a
+ * trailing checksum). Shared by {@link parseFf09SettingsResponse} and the Solix param decoder.
+ */
+export declare function walkFf09Tlv(buf: Buffer, start: number, end: number): Map<number, Buffer>;
 /** Read a little-endian u16 out of a TLV field buffer (throws on a missing/short field — a caller-side bug, not a wire ambiguity). */
 export declare function readFf09U16LE(field: Buffer | undefined, name: string): number;
 /** Read a single byte out of a TLV field buffer (throws on a missing field — same convention as {@link readFf09U16LE}). */

package/dist/transport/http/index.d.ts

@@ -3,3 +3,4 @@ export { randomPhoneModel, randomUserAgent } from "./phone-model.js";
 export * from "./decodeImageV1.js";
 export * from "./decodeImageV2.js";
 export { listLightEffects, listAiSceneRecommendations, type LightEffectSummary } from "./light-catalog.js";
+export { SolixClient, type SolixClientOptions, type SolixLoginResult, type SolixSession, type SolixPersisted, type SolixSessionStore, } from "./solix-client.js";

package/dist/transport/http/solix-client.d.ts

@@ -0,0 +1,158 @@
+/**
+ * A minimal client for the Anker Solix power-station cloud, driven by the SAME account login the
+ * eufy client uses.
+ *
+ * Why this is separate from the eufy device client: Solix shares Anker's `algo_ecdh` passport (so
+ * {@link prepareKeyExchange} / {@link encryptLoginPassword} / {@link signRequest} are reused verbatim
+ * for the login handshake) but exposes a different device backend — its own `app-name`, host, and
+ * bootstrap key (`SOLIX_APP_NAME`, `SOLIX_DEFAULT_API_HOST`, {@link SOLIX_LOCAL_KEY_HEX}) —
+ * and its authenticated resource reads are PLAIN JSON, carrying only the auth token and a
+ * `gtoken = md5(user_id)`, with no per-request encryption or signature. This client therefore does
+ * the encrypted passport handshake to obtain a token, then makes plain authenticated reads.
+ *
+ * This is the wire client (transport layer): it returns the vendor's typed JSON as received. Building
+ * those records into capability-driven `SolixDevice` models is the model layer's job — see
+ * `discoverSolixDevices()` — so the two stay decorrelated (transport never imports model).
+ */
+import { type SessionStore, type SolixDeviceRecord, type SolixProductCategory } from "../../core/index.js";
+import type { SecureMqttCredentials } from "../mqtt/secure-mqtt.js";
+/** An authenticated Solix session — the token + the derived `gtoken` + the resolved API host. */
+export interface SolixSession {
+    authToken: string;
+    userId: string;
+    /** `md5(user_id)` — sent as the `gtoken` header on every authenticated read. */
+    gtoken: string;
+    /** The regional API host the account resolved to (e.g. the EU shard). */
+    apiHost: string;
+    /** Unix seconds; 0 when the server did not supply one. */
+    tokenExpiresAt: number;
+}
+/**
+ * Outcome of {@link SolixClient.login}. `2fa` mirrors the eufy passport: the server sent a code and
+ * the client holds a limited token — call {@link SolixClient.submitVerifyCode} to finish.
+ */
+export type SolixLoginResult = {
+    status: "ok";
+    session: SolixSession;
+} | {
+    status: "2fa";
+    method: string;
+};
+/** Options for {@link SolixClient}. */
+export interface SolixClientOptions {
+    email: string;
+    password: string;
+    /** ISO-3166 alpha-2; defaults to "US". Sent as `country` and `ab`. */
+    countryCode?: string;
+    /** Override the API host (skips domain-estimate). Defaults to estimate → `SOLIX_DEFAULT_API_HOST`. */
+    apiHost?: string;
+    /** App version reported to the cloud. */
+    appVersion?: string;
+    /**
+     * Stable per-install device id (UUID). The auth token is bound to it, and a shifting id looks like
+     * a new device each run and re-triggers 2FA. Defaults to a deterministic id derived from the email
+     * (stable across runs); a store's saved id wins over this.
+     */
+    openudid?: string;
+    /** Persist the token + device id so a dedicated account logs in once and reuses it until expiry. */
+    store?: SolixSessionStore;
+    /** Injected fetch (for tests). Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/** What {@link SolixSessionStore} holds: the stable device id and (once logged in) the session. */
+export interface SolixPersisted {
+    openudid: string;
+    session?: SolixSession;
+}
+/**
+ * A place to persist a Solix session across process runs — the core {@link SessionStore} parameterised on
+ * the Solix record shape, so `FileSessionStore` serves it as-is. The device id survives token expiry (so
+ * the account keeps seeing the same device and does not re-prompt 2FA), and a live session is reused
+ * until it expires.
+ */
+export type SolixSessionStore = SessionStore<SolixPersisted>;
+/**
+ * Login + read client for one Anker account's Solix devices. Construct with the account
+ * credentials, `await login()`, then read {@link getDevices} / {@link getSites} / {@link
+ * getUserMqttInfo}. Not tied to any host runtime.
+ */
+export declare class SolixClient {
+    private readonly email;
+    private readonly password;
+    private readonly country;
+    private readonly appVersion;
+    private readonly doFetch;
+    private readonly store?;
+    private readonly openudid;
+    private apiHost;
+    private session_?;
+    /** Carried between {@link login} and {@link submitVerifyCode} while a 2FA code is outstanding. */
+    private pending2fa?;
+    /**
+     * Resolve the device id (explicit → stored → deterministic from the email, so it is stable and does
+     * not re-trigger 2FA) and adopt a stored session that has not expired, so a warm start skips the
+     * handshake. An explicit `opts.apiHost` outranks a stored session's host in both cases: it is an
+     * override that also skips domain-estimate, and every read goes through `this.apiHost`.
+     */
+    constructor(opts: SolixClientOptions);
+    /** Persist the current device id (+ session, if any) when a store is configured. */
+    private persist;
+    /** The authenticated session, once {@link login} has resolved to `ok`. */
+    get session(): SolixSession | undefined;
+    /**
+     * Headers for the login/key-exchange path, which carry the device id. Authenticated resource reads
+     * must NOT send `openudid` — the gateway rejects a token-bearing read that also carries a device id
+     * (`401 token error`) — so those use {@link baseHeaders} directly.
+     */
+    private authHeaders;
+    /** Base headers common to every Solix request. */
+    private baseHeaders;
+    /** One request path for every Solix call (GET or POST) — always parses through the non-JSON guard. */
+    private send;
+    /** POST helper for the login/key-exchange path (which builds its own bespoke headers per request). */
+    private post;
+    /** Resolve the regional API host via domain-estimate (best-effort; keeps the default on failure). */
+    private estimateHost;
+    /** Do the localKey-bootstrapped ECDH key exchange and return the negotiated session key. */
+    private keyExchange;
+    /** Build the encrypted, signed `/passport/login` request body + headers for the negotiated key. */
+    private postLogin;
+    /**
+     * Turn a decrypted `/passport/login` payload into an `ok`/`2fa` result, establishing the session on
+     * `ok`. The passport marks a pending 2FA with a non-empty `fa_info.info`, and empties it once the code
+     * has been satisfied.
+     */
+    private classifyLogin;
+    /** Decrypt a login envelope's `data` (base64 `IV(16)||AES-128-CBC`, keyed by the share key). */
+    private decryptLogin;
+    /**
+     * Authenticate with the account credentials. Resolves to `ok` with a {@link SolixSession}, or `2fa`
+     * when the passport sent a code — then call {@link submitVerifyCode}. A session that is already fresh
+     * (adopted from a store) is answered without a handshake.
+     */
+    login(): Promise<SolixLoginResult>;
+    /** Complete a `2fa` login with the code the passport sent. */
+    submitVerifyCode(code: string): Promise<SolixLoginResult>;
+    /**
+     * One authenticated PLAIN read for both GET and POST endpoints (no per-request encryption; carries
+     * the auth token + `gtoken` only). Routes through {@link send} so every read keeps the non-JSON guard.
+     */
+    private authed;
+    /**
+     * The account's bound Solix devices (flat list; may be empty when devices live under sites). The
+     * gateway's JSON is asserted to {@link SolixDeviceRecord} here, at the one trust boundary — every field
+     * beyond `device_sn`/`product_code` is optional on the record, so a caller reads them defensively.
+     */
+    getDevices(): Promise<SolixDeviceRecord[]>;
+    /** The account's sites (systems); devices are typically grouped under a site. */
+    getSites(): Promise<unknown[]>;
+    /** Per-user AWS-IoT MQTT credentials (cert/key/endpoint/thing) for the real-time device plane. */
+    getUserMqttInfo(): Promise<SecureMqttCredentials>;
+    /**
+     * The pairable-product catalog (categories → products). This is Anker's product registry, not the
+     * account's devices — fetch it to label a discovered device's model code with a marketing name and
+     * category. Pair with {@link buildModelIndex}. It is a live endpoint, so it stays current without a
+     * baked-in table.
+     */
+    getProductCatalog(): Promise<SolixProductCategory[]>;
+}

package/dist/transport/http/solix-constants.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Anker "Solix" cloud endpoints + app-line constants for {@link SolixClient}.
+ *
+ * Solix runs the SAME `algo_ecdh` passport as the eufy_mega account stack, re-skinned under a
+ * different `app-name` with its own API host and key-exchange bootstrap key (the bootstrap key lives
+ * in `core` beside its siblings — {@link SOLIX_LOCAL_KEY_HEX}). One Anker/eufy account logs in here
+ * with the exact login handshake the eufy client uses; only these constants differ. Authenticated
+ * resource reads, by contrast, are PLAIN JSON carrying just the auth token + `gtoken`.
+ */
+/** The `app-name` header value that scopes the passport + API to the Solix product. */
+export declare const SOLIX_APP_NAME = "anker_power";
+/** Domain-estimate bootstrap host. `POST /passport/estimate_domain {ab,mode:1}` answers the shard host. */
+export declare const SOLIX_ESTIMATE_HOST = "uniapp-api-pr.anker.com";
+/** EU-shard API host — the estimate result, and the fallback when estimate is skipped. */
+export declare const SOLIX_DEFAULT_API_HOST = "ankerpower-api-eu.anker.com";
+/** Solix cloud paths used by {@link SolixClient}. */
+export declare const SOLIX_ENDPOINTS: {
+    readonly estimateDomain: "/passport/estimate_domain";
+    readonly keyExchange: "/openapi/oauth/key/exchange";
+    readonly login: "/passport/login";
+    /** Bound devices for the account (flat list). */
+    readonly getRelateAndBindDevices: "/power_service/v1/app/get_relate_and_bind_devices";
+    /** Sites (systems) the account owns; devices are grouped under a site. */
+    readonly getSiteList: "/power_service/v1/site/get_site_list";
+    /** Per-user AWS-IoT MQTT credentials (cert/key/endpoint/thing) for the real-time device plane. */
+    readonly getUserMqttInfo: "/v1/openapi/devicemanage/get_user_mqtt_info";
+    /** GET: the pairable-product catalog (categories → products), for labelling model codes. */
+    readonly productCategories: "/power_service/v1/product_categories";
+};

package/dist/transport/mqtt/index.d.ts

@@ -3,3 +3,5 @@ export * from "./topics.js";
 export * from "./app-client-id.js";
 export * from "./broker-discovery.js";
 export * from "./biz-stream.js";
+export { SolixMqtt } from "./solix-mqtt.js";
+export type { SolixMqttOptions, SolixMqttDevice, SolixReading, SolixParamFrame, SolixChannel } from "./solix-mqtt.js";

package/dist/transport/mqtt/secure-mqtt.d.ts

@@ -93,12 +93,25 @@ export declare class SecureMqtt extends EventEmitter implements RealtimeTranspor
      * four topics for `eufy_life`).
      *
      * The grants are INSPECTED, not assumed: AWS IoT answers a policy-denied filter with a
-     * `SUBACK_FAILURE` (`0x80`) grant rather than failing the SUBSCRIBE, so subscribing with a credential
+     * SUBACK_FAILURE (`0x80`) grant rather than failing the SUBSCRIBE, so subscribing with a credential
      * whose scope doesn't cover the topic looks identical to success and then delivers nothing. A denied
      * topic is reported via `error` naming the credential scope; only an all-denied device throws, so a
      * line that grants its state channel but refuses (say) the OTA leg still works.
      */
     subscribeDevice(device: EufyDevice): Promise<void>;
+    /**
+     * Subscribe to explicit topic filters, returning the topics that were granted. A scope-denied filter
+     * comes back with SUBACK_FAILURE rather than an error (AWS IoT quirk), so it is dropped from the result
+     * instead of throwing — callers that need every leg check the returned list. Used by lines whose topic
+     * vocabulary isn't the eufy `subscribeTopics` shape (e.g. Anker Solix `dt/{app}/{pn}/{sn}`).
+     */
+    subscribe(topics: string[]): Promise<string[]>;
+    /**
+     * Split SUBACK grants into granted vs scope-denied topics. AWS IoT marks a policy-denied filter with a
+     * SUBACK_FAILURE (`0x80`) grant rather than failing the SUBSCRIBE, so the two subscribe paths share
+     * this split and layer their own policy (drop vs report) on top.
+     */
+    private partitionGrants;
     /**
      * Publish a raw payload to an MQTT topic (the command leg — `cmd/{app}/{pn}/{sn}/req`). The `body`
      * is a pre-built envelope the caller supplies (the command router builds it). QoS 1 by default (the

package/dist/transport/mqtt/solix-mqtt.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Live telemetry for Anker Solix devices over the AWS-IoT MQTT plane.
+ *
+ * The transport is the shared `SecureMqtt` — the exact same anker AWS-IoT broker + per-user
+ * client-cert mutual TLS the eufy device path uses; a Solix account's `get_user_mqtt_info` result maps
+ * straight onto {@link SecureMqttCredentials}. Solix devices publish telemetry continuously on
+ * `dt/{app_name}/{product_code}/{device_sn}/param_info` as an **ff09 TLV frame** (the same framing
+ * family as {@link parseFf09SettingsResponse}), so this module only adds the Solix topic + a small
+ * ff09 param decoder on top of the reused transport.
+ *
+ * Frame layout (observed on a Smart Meter Gen 2 / AE1X0):
+ *   ff09 | len(u16 LE, incl. trailing XOR checksum) | 5-byte header | TLV fields | xor
+ * each TLV field is `tag(1) | len(1) | value(len)`; measurement fields carry `type(1) | 4 bytes`,
+ * type `0x05` = float32 LE. Field `a2` is the device serial (ASCII after a leading type byte).
+ */
+import { EventEmitter } from "node:events";
+import { type SecureMqttCredentials } from "./secure-mqtt.js";
+import { type Logger } from "../../core/index.js";
+/** A decoded telemetry channel: the raw value plus float/uint interpretations of a 4-byte payload. */
+export interface SolixChannel {
+    /** The leading type byte (`0x05` = float32 LE for the meter's measurement channels). */
+    type: number;
+    raw: Buffer;
+    /** Present when the payload is 4 bytes: little-endian float32. */
+    float?: number;
+    /** Present when the payload is 4 bytes: little-endian uint32. */
+    uint?: number;
+}
+/** A parsed ff09 param frame: the device serial (from `a2`) + the raw TLV field map keyed by tag. */
+export interface SolixParamFrame {
+    deviceSn?: string;
+    /** tag byte → value bytes (still including the per-field leading type byte for measurement fields). */
+    fields: Map<number, Buffer>;
+}
+/**
+ * Telemetry field tags for the Smart Meter (AE1X0) that we emit under a stable NAME, keyed by ff09 tag
+ * byte. Only tags whose tag→name binding is CONFIRMED against a live frame live here:
+ *
+ * - `0xac` = `meterVoltageL1` — confirmed against live single-phase data (a nominal mains voltage).
+ *
+ * Every other measurement tag still surfaces as `channel_<hex tag>` (see {@link solixReadings}), so
+ * nothing on the wire is lost — a caller reads unconfirmed tags there. The names are deliberately NOT
+ * asserted for the rest: the app exposes the field *list*, but the tag→name *binding* below is a
+ * structural inference until a known-load capture pins it, and a mislabelled live float is worse than an
+ * honest `channel_<tag>`. The recovered candidates, to re-add one line each (moving the tag from this
+ * comment to the map above) as a known-load capture confirms each binding:
+ *
+ *   0xa8 meterPowerL1   0xa9 meterPowerL2   0xaa meterPowerL3   0xab meterPowerTotal
+ *   0xad meterVoltageL2 0xae meterVoltageL3 0xaf meterCurrentL1 0xb0 meterCurrentL2
+ *   0xb1 meterCurrentL3 0xb2 meterCurrentTotal 0xb3 meterImportEnergy 0xb4 meterExportEnergy
+ */
+export declare const SOLIX_METER_FIELD_NAMES: Readonly<Record<number, string>>;
+/** Interpret one TLV value as a telemetry channel (leading type byte + payload). */
+export declare function readSolixChannel(value: Buffer | undefined): SolixChannel | undefined;
+/**
+ * Decode an ff09 Solix param frame into its serial + TLV field map. Returns `null` for a non-ff09
+ * buffer, a length field that doesn't fit, or a bad checksum. Validates the trailing XOR checksum first
+ * (so a corrupted frame is rejected rather than yielding plausible floats), then walks `tag|len|value`
+ * from the first `0xa1` tag to the declared length minus the checksum byte via the shared
+ * `walkFf09Tlv` (bounded by `end`, so a field length can't overrun into the checksum).
+ */
+export declare function decodeSolixParamFrame(buf: Buffer): SolixParamFrame | null;
+/**
+ * Reduce a param frame to named + raw telemetry values. Tags below `0xa6` are skipped — `a1`/`a2`/`a3`
+ * carry the field count, the serial and the status, not measurements. A measurement channel is one whose
+ * leading type byte is `0x05` (float32 LE over a 4-byte payload); any other type is a non-measurement
+ * param and contributes nothing. Each measurement is emitted under `channel_<hex tag>`, and additionally
+ * under its name when the tag has a confirmed one in {@link SOLIX_METER_FIELD_NAMES}.
+ */
+export declare function solixReadings(frame: SolixParamFrame): Record<string, number>;
+/** A live telemetry sample emitted by {@link SolixMqtt} as a `reading` event. */
+export interface SolixReading {
+    deviceSn: string;
+    productCode: string;
+    topic: string;
+    frame: SolixParamFrame;
+    values: Record<string, number>;
+}
+/** The minimum device shape {@link SolixMqtt.watch} needs (as returned by `SolixClient.getDevices`). */
+export interface SolixMqttDevice {
+    device_sn: string;
+    product_code: string;
+}
+/** Options for {@link SolixMqtt}. */
+export interface SolixMqttOptions {
+    /** `get_user_mqtt_info` result — carries endpoint, cert/key, app_name, thing_name, user_id. */
+    mqttInfo: SecureMqttCredentials;
+    /** Override the MQTT clientId. Defaults to the cert CN (`thing_name`), distinct from the app's id. */
+    clientId?: string;
+    /**
+     * Account/user id (40-hex) for the arming `account_id` + heartbeat topic. Defaults to
+     * `mqttInfo.user_id`; set it if the credentials omit it.
+     */
+    userId?: string;
+    /**
+     * How often (ms) to re-send the device-info arming request that keeps realtime telemetry flowing.
+     * The device stops pushing `param_info` when no client keeps requesting it (the app re-arms on every
+     * foreground resume + a periodic heartbeat), so a passive subscriber goes silent after the server's
+     * reporting window closes. Default 25s — inside the observed ~30s cadence with keepalive 60. Set `0`
+     * to disable arming (subscribe-only, the old behaviour).
+     */
+    armIntervalMs?: number;
+    /**
+     * The `head.client_id` stamped into the command/heartbeat envelopes — the app-shaped
+     * `android-{app_name}-{user_id}-{mqttUuid}-{ts}` (see {@link buildAppShapedClientId}). Defaults to
+     * that shape built from {@link mqttUuid}. Pass this to pin the whole string.
+     */
+    appClientId?: string;
+    /**
+     * Stable 16-hex install UUID for the app-shaped client id. Defaults to one derived deterministically
+     * from the user id ({@link mqttUuidFrom}) — no storage needed, so the broker sees one stable client
+     * across restarts.
+     *
+     * The trade this makes: the default seed is the **account** id, which every client on that account
+     * shares, so two clients on one account derive the same uuid → the same `client_id`, and the broker
+     * evicts one to admit the other (they take the channel from each other indefinitely). Restart
+     * stability is the common case and this is the deliberate default, but pass an explicit `mqttUuid`
+     * (per host/install) when more than one client runs on the same account, to be told apart.
+     */
+    mqttUuid?: string;
+    /** The account's `site_id` for the `power_site` heartbeat. Omitted from the frame when unknown. */
+    siteId?: string;
+    logger?: Logger;
+}
+/**
+ * Subscribe to a Solix device's live telemetry and emit decoded `reading` events. Reuses
+ * `SecureMqtt` for the connection; adds only the Solix data topic + ff09 param decoding.
+ *
+ *   const mqtt = new SolixMqtt({ mqttInfo: await solix.getUserMqttInfo() });
+ *   mqtt.on("reading", (r) => console.log(r.deviceSn, r.values.meterVoltageL1));
+ *   await mqtt.watch(device);   // device = a SolixClient.getDevices() entry
+ */
+export declare class SolixMqtt extends EventEmitter {
+    private readonly transport;
+    private readonly appName;
+    private readonly userId?;
+    private readonly appClientId;
+    private readonly armIntervalMs;
+    private readonly logger?;
+    private readonly siteId?;
+    private readonly watched;
+    private seq;
+    private armTimer?;
+    /**
+     * Bind to one account's MQTT plane. The envelope `client_id` takes the app's shape
+     * (`android-{app}-{uid}-{mqttUuid}-{ts}`); its `mqttUuid` half must be stable across restarts, or every
+     * restart presents itself to the broker as a new client, so it defaults deterministically from the user
+     * id (see {@link SolixMqttOptions.mqttUuid}) rather than a fresh random per instance.
+     */
+    constructor(opts: SolixMqttOptions);
+    /**
+     * Connect, subscribe to the device's telemetry (+ command-reply) topics, ARM realtime reporting, and
+     * start the re-arm/heartbeat timer so telemetry keeps flowing without the app. Idempotent per device.
+     *
+     * Subscribes ONLY to what the device sends — `param_info` plus the device and account command-reply
+     * channels — never the `…/req` channels, which are the app→device request side this arms on, and would
+     * echo its own publishes back.
+     *
+     * Throws when `param_info` was not granted. A scope-denied filter comes back as SUBACK_FAILURE rather
+     * than an error (see `SecureMqtt.subscribe`), so an unusable subscription otherwise looks like
+     * success: the call would resolve and arm on every interval while no reading ever arrives.
+     *
+     * The re-arm timer is unreffed, so a caller that watches and returns can still exit.
+     */
+    watch(device: SolixMqttDevice): Promise<void>;
+    /** Tear down the connection and stop the re-arm timer. */
+    close(): Promise<void>;
+    /**
+     * Re-arm every watched device and send the site heartbeat. The device only pushes `param_info` while
+     * a client keeps requesting it — this replays the app's `requestDeviceInfo` (cmd 17) + `power_site`
+     * heartbeat (cmd 10); the request frames are reproduced byte-for-byte by {@link buildFf09Request}
+     * (checksum-verified against captured frames in its spec). Best-effort: a publish failure is emitted,
+     * not thrown, so one bad device doesn't stop the rest or kill the timer.
+     */
+    private armAll;
+    /** Publish the device-info arming request (both the "info" and "realtime" ff09 variants the app sends). */
+    private arm;
+    /** The common `head` fields for every cmd envelope; callers add `cmd` + the per-message variable bits. */
+    private makeHead;
+    /**
+     * Build the `{head, payload}` cmd-17 (requestDeviceInfo) envelope carrying a base64 ff09 request.
+     * `account_id` is omitted when the user id is unknown: a live broker cannot tell an empty placeholder
+     * from a real value, so sending `""` would claim an account this client does not have.
+     */
+    private commandEnvelope;
+    /**
+     * The `power_site` heartbeat (cmd 10) envelope the app sends on a timer to keep the session alive.
+     * `site_id` is omitted when unknown, for the same reason `account_id` is in {@link commandEnvelope}.
+     */
+    private heartbeatEnvelope;
+    /**
+     * Decode one inbound MQTT message envelope and emit a `reading` if it carries an ff09 param frame. The
+     * product code and the fallback serial come from the topic (`dt/{app}/{pn}/{sn}/param_info`); the frame's
+     * own `a2` field wins for the serial when it carries one.
+     */
+    private onMessage;
+}
+/**
+ * Pull the ff09 binary frame out of a received message. Solix telemetry arrives as a `{head, payload}`
+ * envelope whose `payload` is a JSON string carrying base64 `data` (or `trans`); `SecureMqtt`
+ * has already JSON-parsed the outer envelope. Returns the decoded frame bytes, or `null`.
+ */
+export declare function extractFf09Payload(raw: unknown): Buffer | null;
+/**
+ * Build the ff09 request frame the app base64-encodes into a `requestDeviceInfo` (cmd 17) command's
+ * `data`. Captured live from the Anker app — request-type tag `a1`=0x22; the `realtime` variant adds
+ * `a2`/`a3` params (this is the one that keeps `param_info` reporting flowing), while `info` is the bare
+ * device-info fetch. Frame:
+ *   `ff09 | len(u16 LE, TOTAL bytes incl. ff09+len+xor) | 5-byte header | a1 01 22
+ *    [| a2 02 01 01 | a3 03 02 2c 01] | fe … <ts32 LE> | xor`
+ * `fe` carries a fresh unix-timestamp nonce; the trailing byte is XOR of every preceding byte (the same
+ * checksum the meter's telemetry frames use — verified to reproduce the captured frames exactly).
+ */
+export declare function buildFf09Request(variant: "info" | "realtime", atUnixSec?: number): Buffer;

package/dist/transport/mqtt/topics.d.ts

@@ -78,3 +78,23 @@ export interface ParsedTopic {
  * so an unparsed topic leaves `deviceSn` unset instead of carrying a guess.
  */
 export declare function parseSecureTopic(topic: string): ParsedTopic | undefined;
+/** The per-device Solix topics for `{appName, productCode, deviceSn}`. */
+export interface SolixDeviceTopics {
+    /** Telemetry the device pushes (SUBSCRIBE) — ff09 `param_info` frames. */
+    paramInfo: string;
+    /** This device's command replies (SUBSCRIBE). */
+    cmdRes: string;
+    /** The device's requestDeviceInfo channel (PUBLISH only — the app arms reporting here). */
+    req: string;
+}
+/** Build the per-device Solix topics. `param_info` is the telemetry we decode; `req` is publish-only. */
+export declare function solixDeviceTopics(appName: string, productCode: string, deviceSn: string): SolixDeviceTopics;
+/** The per-account Solix topics keyed by `user_id`. */
+export interface SolixUserTopics {
+    /** Account-level command replies (SUBSCRIBE). */
+    cmdRes: string;
+    /** The `power_site` heartbeat channel (PUBLISH only). */
+    powerSite: string;
+}
+/** Build the per-account Solix topics. Note: the account `…/req` channel is publish-side and NOT subscribed. */
+export declare function solixUserTopics(appName: string, userId: string): SolixUserTopics;

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

@@ -18,6 +18,23 @@ import type { FfmpegLevel } from "../ffmpeg.js";
 import { SharedLiveSource } from "./shared-live-source.js";
 import { type PowerTier, type SessionManagerOpts } from "./session-manager.js";
 import { FragmentRecording } from "./fragment-recording.js";
+/**
+ * What a caller's own deadline on a station call has to clear, in milliseconds.
+ *
+ * A caller that bounds one of these calls itself races these waits, and a bound below them reports the
+ * caller's own expiry in place of the reason this SDK was about to give — the two are indistinguishable to
+ * whoever reads the outcome, and they call for different next steps. Published so that bound can be derived
+ * rather than copied: a literal in a caller's source is a second source of truth that goes stale silently
+ * when these change.
+ *
+ * `connect` applies to every call on a station, because nothing can be addressed to one before its session is
+ * up. `level2Grace` applies twice where the key is required: the negotiation is re-prompted once.
+ */
+export declare const P2P_STATION_WAITS: {
+    readonly connect: 20000;
+    readonly level2Grace: 25000;
+    readonly level2Settle: 8000;
+};
 /**
  * Options accepted when warming a {@link SharedLiveSource} for a device (all optional).
  *
@@ -90,6 +107,12 @@ export declare class P2PCommandRouter {
     constructor(deps: P2PRouterDeps);
     /** Forward one P2P failure once even when both the session listener and startup waiter observe it. */
     private reportError;
+    /**
+     * Emit a live trace under a station session's handle, for work this router does ON that session before
+     * the session itself records anything — reaching the station, and resolving what a device is on it. Same
+     * handle as everything the session goes on to trace, which is what groups one attempt.
+     */
+    private traceOnStation;
     /**
      * Whether this transport stack drives `dev`'s `ff09-*` commands — true when the device has its own
      * usable P2P endpoint (a non-empty `p2p_did`). The command sink asks each stack this to route a