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

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

@@ -32,6 +32,14 @@ export interface MegaClientConfig {
      * an explicit value pins a fixed one. Not the account identity — that's `phoneModel`.
      */
     mediaUserAgent?: string;
+    /**
+     * Acting name written into the commands that carry an actor field — guard mode and HomeBase alarm
+     * output (`user_name`), a lock's acting username. Trimmed, and blank counts as unset: the default
+     * is the login email's local-part (the whole string when it has no `@`). Attribution only — the
+     * device stores it for its own activity record, and no captured frame shows it being validated
+     * against the account.
+     */
+    accountName?: string;
     /** Persist + reuse the session (token + session key) across runs. Default: in-memory. */
     store?: SessionStore;
     /** Diagnostics sink. Omit for silence; pass a `Logger` (or `new ConsoleLogger()`) to see logs. */
@@ -63,9 +71,34 @@ export declare class MegaApiError extends Error {
  * device-list params carry the same `{param_type, param_value, update_time}` and are not owner-gated.
  */
 export declare const OWNER_ONLY_CODE = 20004;
-/** Thrown when a persisted/expired session is rejected (401). Re-login to recover. */
+/**
+ * Thrown when a persisted/expired session is rejected (401). Re-login to recover.
+ *
+ * It carries the rate the client has already worked out for replacing a rejected token, because the
+ * rejection is where that rate stops being the client's alone: a login driven from here spends the same
+ * session the client's own recovery would have, and repeated logins are what makes an account start
+ * demanding captchas. {@link retryAfterMs} is how long the next replacement is barred for, and
+ * {@link contended} whether this rejection landed inside that bar — the shape repeated displacement has.
+ */
 export declare class SessionExpiredError extends Error {
-    constructor(message: string);
+    /**
+     * How long the next session replacement is barred for, in milliseconds; `0` when nothing bars one now.
+     *
+     * The remainder of the client's own hold-off, which doubles per consecutive replacement and is capped —
+     * and which every replacement extends, whether the client spent it or a login made on this error did.
+     */
+    readonly retryAfterMs: number;
+    /**
+     * Whether this rejection landed inside that bar — a token replaced recently and rejected again since.
+     *
+     * It says the session is being DISPLACED rather than expiring: something else is signing in on this
+     * account, and replacing the token again only trades one login for another.
+     */
+    readonly contended: boolean;
+    constructor(message: string, opts?: {
+        retryAfterMs?: number;
+        contended?: boolean;
+    });
 }
 /**
  * eufy cloud gateway error codes — the numeric `code` carried in a response envelope alongside the
@@ -179,6 +212,13 @@ export declare class MegaHttpClient {
     private sessionKey?;
     /** Per-host ECDH session keys for non-mega gateways (e.g. eufylife) keyed by host. */
     private readonly sessionKeys;
+    /**
+     * The held credential. `userId` is the login reply's `ap_cloud_user_id` where it has one — the Anker
+     * Passport cloud's id — while `accountUserId` is the eufy account's own `user_id`.
+     *
+     * The `gtoken` header is hashed from `accountUserId`: that is the id the gateway recomputes the header
+     * from, rejecting a disagreement with `"gtoken not equal userid error"`.
+     */
     private auth_?;
     /** captcha_id of an in-flight challenge, held between login() and solveCaptcha(). */
     private pendingCaptchaId?;
@@ -208,9 +248,11 @@ export declare class MegaHttpClient {
     private loggingIn;
     /** The one in-flight re-login every call rejected on the same dead token waits on. */
     private reauthAttempt?;
-    /** Replacements since the held session last proved stable, and when the last one ran — see {@link recoveryDue}. */
+    /** Replacements since the held session last proved stable, and when the last one ran — see {@link holdOffRemainingMs}. */
     private recoveries;
     private lastRecoveryAt;
+    /** A token of ours has been rejected and not yet replaced — see {@link noteTokenReplacement}. */
+    private rejectedTokenPending;
     constructor(cfg: MegaClientConfig);
     /**
      * Install the session the store holds, if it holds a usable one: the token + its bound ECDH key, skipping
@@ -231,10 +273,15 @@ export declare class MegaHttpClient {
     /** The active region shard (e.g. `"eu-pr"`, `"us-pr"`), set after {@link login} or a region override. */
     get regionShard(): RegionShard;
     /**
-     * The logged-in account's display name — the login email's local-part (e.g. `someone+tag` for
-     * `someone+tag@example.com`). This is the string the app writes into the ff09 command's acting
-     * "username" field (verified against a captured T8531 unlock frame). Falls back to the whole email
-     * if it has no `@`.
+     * The name commands attribute themselves to — {@link MegaClientConfig.accountName} when the config
+     * pins one (trimmed; blank counts as unset), otherwise the logged-in account's display name, which
+     * is the login email's local-part (e.g. `someone+tag` for `someone+tag@example.com`) and falls back
+     * to the whole email if it has no `@`.
+     *
+     * The local-part is the string the app writes into the ff09 command's acting "username" field
+     * (verified against a captured T8531 unlock frame), so it is the faithful default. An override is a
+     * different LABEL for the same account, not a different identity: the session authenticates on the
+     * token and the device record's member ids, neither of which this touches.
      */
     get accountName(): string;
     /**
@@ -246,7 +293,14 @@ export declare class MegaHttpClient {
      */
     private baseHeaders;
     /**
-     * The account-credential headers every authed call carries — `x-auth-token` + `gtoken` (`md5(userId)`).
+     * The id `gtoken` is hashed from — the account's own `user_id`, which is what the gateway recomputes the
+     * header from. One place so the two header paths cannot drift on which of the session's ids that is.
+     *
+     * Call only where `auth_` is already established; every header path guards it.
+     */
+    private gtokenUserId;
+    /**
+     * The account-credential headers every authed call carries — `x-auth-token` + `gtoken`.
      * One place so the signed path, the key-exchange and the bearer path can't drift on what "authed" means.
      */
     private authTokenHeaders;
@@ -353,7 +407,13 @@ export declare class MegaHttpClient {
     registerPushToken(token: string): Promise<void>;
     /** Download raw bytes from a push-media URL using the active account session. */
     downloadMedia(url: string): Promise<Buffer>;
-    /** Download push image bytes and decrypt a recognized v1 wrapper when its device key input is available. */
+    /**
+     * Download push image bytes and decrypt a recognized v1 wrapper when its device key input is available.
+     *
+     * A decoder throw is tagged `decode-failed`: to anything downstream, the difference between "the
+     * bytes never arrived" and "the bytes arrived and the wrapper would not decrypt" is the difference
+     * between a network problem and a key problem, and one of them is this SDK's to fix.
+     */
     downloadImage(url: string, p2pDid?: string): Promise<Buffer>;
     /** The security-app data host for this region (face recognition, media, etc.). */
     private securityAppHost;
@@ -467,6 +527,26 @@ export declare class MegaHttpClient {
      * and a caller is told the honest reason instead of being served a fight.
      */
     private recoveryDue;
+    /**
+     * How much longer a token replacement must wait, in milliseconds; `0` when one may run now.
+     *
+     * The wait doubles per consecutive replacement and is capped, and it is what {@link recoveryDue} gates
+     * this client's own recovery on — and what {@link SessionExpiredError.retryAfterMs} hands a host that
+     * drives its own. One function so the two cannot disagree about the rate, which they would have to for
+     * a host to be told it may retry while this client is still holding off.
+     */
+    private holdOffRemainingMs;
+    /**
+     * Count one token replacement against the hold-off, and clear the rejection it answered.
+     *
+     * Every replacement passes through here, wherever it was spent from: {@link recoverRejectedSession}, and
+     * a {@link login} that follows a rejection this client surfaced. A hold-off that counted only its own
+     * would be no bound at all — the wait would sit at its first value however many sessions had been spent,
+     * and {@link SessionExpiredError.retryAfterMs} would report a minute while logins ran every few seconds.
+     * Which of the two counted a given replacement is the flag: the recovery path clears it before logging
+     * in, so the login cannot count the same one again.
+     */
+    private noteTokenReplacement;
     /**
      * Note that the held session is working. A replacement that keeps serving calls for long enough is not
      * contention, so the hold-off is forgotten and the next genuine expiry recovers immediately.

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

@@ -0,0 +1,270 @@
+/**
+ * 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 SolixPowerCutoffOption, type SolixProductCategory, type SolixSiteRecord, type SolixSiteScene, type SolixSocParams } 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.
+     *
+     * `gtoken` is hashed from `ap_cloud_user_id` where the reply carries one, `user_id` otherwise. Whether
+     * this gateway recomputes the header from `user_id` specifically — as the mega gateway does, rejecting a
+     * disagreement with `"gtoken not equal userid error"` — is unverified here: no Solix response has been
+     * observed refusing the header, which is consistent with the two ids agreeing on the accounts seen.
+     */
+    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>;
+    /**
+     * On a rejected `/passport/login` (non-zero code, so `data` is an error envelope not the encrypted
+     * payload), throw a diagnostic that names WHY the passport refused — the throttle (`26161`, "too
+     * frequent") vs a challenge it wants the client to satisfy. The passport marks a required captcha with
+     * a `captcha_id`/`item`; our headless client cannot answer one, so surfacing it distinguishes "wait
+     * out the rate-limit" from "a captcha is required — clear it in the app". No secrets are logged, only
+     * the code, message, and which challenge fields are present.
+     */
+    private assertLoginAccepted;
+    /** 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.
+     *
+     * Self-heals a **displaced session**: Anker allows ~one session per account, so another login (the app,
+     * or a second client) invalidates this token and reads then fail with {@link SOLIX_TOKEN_KICKED_CODE}
+     * ("token does not exist because it was kicked out"). On that code this re-logs in once and retries, so
+     * a running client recovers on its own instead of failing every read until its session store is cleared.
+     */
+    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 grouped under a site. Each record carries its
+     * `site_device_list` (the member devices), which {@link discoverSolixSites} resolves into a
+     * capability-driven `SolixSite`. Asserted to {@link SolixSiteRecord} at this trust boundary — and
+     * `site_id` (the one field the model layer keys a `SolixSite` on) is validated here, so a record the
+     * cloud returns without a usable id is dropped rather than surfacing a `SolixSite` with `id ===
+     * undefined`; every other field is optional and read defensively.
+     */
+    getSites(): Promise<SolixSiteRecord[]>;
+    /** Per-user AWS-IoT MQTT credentials (cert/key/endpoint/thing) for the real-time device plane. */
+    getUserMqttInfo(): Promise<SecureMqttCredentials>;
+    /**
+     * Read a site's "scene" snapshot — the app's dashboard read for a system, a plain authed read. Its
+     * battery detail (`solarbank_info.solarbank_list[]`) carries clean, correctly-named fields including
+     * `bat_temperature`, which the realtime `ff09` MQTT push does NOT reliably carry (the fast frame's BMS
+     * blob is empty, so the decoder withholds temperature). This is therefore a low-rate BACKSTOP for those
+     * gap fields — NOT the realtime source: live power/SOC still come from the MQTT push (which is what the
+     * app itself refreshes from every ~5 s; there is no clean-JSON scene PUSH). Verified live against the
+     * `ff09` floats — the two agree to the watt at the same instant.
+     */
+    getSiteScene(siteId: string): Promise<SolixSiteScene>;
+    /**
+     * 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[]>;
+    /**
+     * Write device attributes — a CONTROL write, e.g. the Solarbank ambient light
+     * `{ ambient_light_switch: 0 | 1 }` (0 = on, 1 = off). Unlike the plain authenticated reads, a write
+     * must be **encrypted + signed** with a freshly negotiated `algo_ecdh` key: the gateway accepts an
+     * unsigned write with `code 0` but the device never applies it. The token-bearing request also must
+     * NOT carry the device id (`openudid`), or the gateway answers `401 token error`. Both verified live
+     * on an AE103 (the LED-enable bit in the `ba` telemetry flips exactly as commanded).
+     */
+    setDeviceAttrs(deviceSn: string, attributes: Record<string, unknown>): Promise<void>;
+    /**
+     * A CONTROL write: `algo_ecdh`-encrypted + signed, token-bearing but WITHOUT `openudid`. Every device
+     * control the account performs (set_device_attrs, set_power_cutoff, …) goes through this — the gateway
+     * accepts an unsigned/plain write with `code 0` but the device never applies it, and adding `openudid`
+     * to the token-bearing request returns `401 token error`. Both verified live on an AE103.
+     */
+    private encryptedWrite;
+    /** Turn the Solarbank's ambient LED on/off — a confirmed `set_device_attrs` write. */
+    setAmbientLight(deviceSn: string, on: boolean): Promise<void>;
+    /**
+     * Read device attributes — a plain authenticated read (unlike the encrypted write). `attributes`
+     * names the keys to fetch (e.g. `["screen_off_time"]`); an empty list asks for the device's default
+     * set. Returns the gateway's attribute map as-is (values are device-typed — numbers, strings). Used
+     * to reflect a control's live state, e.g. the display/light off-timeout.
+     */
+    getDeviceAttrs(deviceSn: string, attributes?: string[]): Promise<Record<string, unknown>>;
+    /**
+     * Set the Solarbank display's screen-off timeout, in SECONDS (`screen_off_time`). The app's picker
+     * offers 10/20/30 s and 1/5/30 min; the LCD backlight — and with it the ambient LED that the screen
+     * gates — turns off after this idle period. This is the raw-seconds write; the caller maps its own UI
+     * options to seconds. The "Never" (always-on) sentinel is device-defined and NOT assumed here — pass
+     * the exact integer read back from {@link getDeviceAttrs} while the device is in that mode.
+     */
+    setScreenOffTime(deviceSn: string, seconds: number): Promise<void>;
+    /**
+     * Read the Solarbank's battery discharge-cutoff (minimum-SOC) options — a plain authed read.
+     * The gateway returns a preset list (`power_cutoff_data`): each entry is a selectable minimum
+     * state-of-charge `output_cutoff_data` (percent) with its `id` and `is_selected` flag. The caller
+     * presents these options and writes the chosen `id` back via {@link setPowerCutoff} — the values and
+     * ids come from the device, never assumed. `siteId` is optional (the device knows its own cutoff).
+     */
+    getPowerCutoff(deviceSn: string, siteId?: string): Promise<SolixPowerCutoffOption[]>;
+    /**
+     * Select the Solarbank's battery discharge-cutoff (minimum SOC) by option id — a control write.
+     * `cutoffDataId` MUST be an `id` returned by {@link getPowerCutoff} for this device (the preset the
+     * user picked), never a raw percentage; the gateway maps the id to its cutoff percent.
+     */
+    setPowerCutoff(deviceSn: string, cutoffDataId: number): Promise<void>;
+    /** The `param_type` under which the Solarbank's SOC-limit block lives (verified live on an AE103). */
+    private static readonly SOC_PARAM_TYPE;
+    /** `cmd` value that scopes the `site/*_site_device_param` family (from the app's request builder). */
+    private static readonly SITE_DEVICE_PARAM_CMD;
+    /**
+     * Read one of a site's "device param" blocks by `param_type` — a plain authenticated read whose
+     * `data.param_data` is itself a JSON STRING (the vendor double-encodes it). Returns the parsed inner
+     * object, or `{}` when the block is empty (the gateway answers `code 0` with an empty `param_data`
+     * for a `param_type` that does not apply to the site's hardware). The caller owns the inner shape.
+     */
+    private getSiteDeviceParam;
+    /**
+     * Read the Solarbank's battery SOC-limit settings (`param_type "27"`) — a plain authenticated read.
+     * Returns `undefined` when the site carries no SOC block (e.g. non-Solarbank hardware). The realtime
+     * `dischargeLowerLimit` also arrives on the MQTT `b5` telemetry blob; this is the authoritative,
+     * app-synced source for `chargeUpperLimit`. `backupReserve` (with its enable switch) also has a second
+     * source under the same name, the realtime MQTT `b5` frame; whether the two agree while the switch is
+     * OFF is not yet verified. Verified live against a known AE103 setting (discharge 20 / charge 80).
+     */
+    getSafetySocParams(siteId: string): Promise<SolixSocParams | undefined>;
+    /**
+     * Write the Solarbank's battery SOC limits — an `algo_ecdh`-encrypted + signed control write. This is
+     * **read-modify-write**: it first reads the current `param_type "27"` block and overlays only the
+     * fields the caller supplies, so changing the discharge limit alone never clobbers the charge limit,
+     * backup reserve, or calibration toggle. `changes` values are whole-percent integers. The full block
+     * (all five keys) is sent, matching the app's `SocSettingParam.toJson`. Throws if the site has no SOC
+     * block to modify. Returns the merged parameters that were written (for an immediate optimistic echo).
+     */
+    setSafetySocParams(siteId: string, changes: Partial<SolixSocParams>): Promise<SolixSocParams>;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * 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";
+    /** POST (encrypted+signed): write device attributes, e.g. `{ambient_light_switch: 0|1}`. */
+    readonly setDeviceAttrs: "/power_service/v1/app/device/set_device_attrs";
+    /** POST (plain authed): read device attributes, e.g. the display `screen_off_time` (seconds). */
+    readonly getDeviceAttrs: "/power_service/v1/app/device/get_device_attrs";
+    /** POST (plain authed): the battery discharge-cutoff (minimum-SOC) preset options. */
+    readonly getPowerCutoff: "/power_service/v1/app/compatible/get_power_cutoff";
+    /** POST (encrypted+signed): select the discharge-cutoff preset by `cutoff_data_id`. */
+    readonly setPowerCutoff: "/power_service/v1/app/compatible/set_power_cutoff";
+    /**
+     * POST (plain authed): the site "scene" snapshot — the same clean Solarbank/grid telemetry the app
+     * reads on load/refresh. Used as a low-rate BACKSTOP for the fields the realtime `ff09` push doesn't
+     * carry reliably (notably `bat_temperature`), NOT as the realtime source (that is the MQTT push).
+     */
+    readonly getSiteScene: "/power_service/v2/site/platform_get_site_scene";
+    /**
+     * POST (plain authed): read a site "device param" block by `param_type`. Body is
+     * `{ site_id, param_type, cmd: 246 }`; the response's `data.param_data` is a JSON STRING the caller
+     * parses. The Solarbank's SOC-limit settings live under `param_type "27"` (charge/discharge limits,
+     * backup reserve) — verified live on an AE103 (`"18"` returns empty for this device).
+     */
+    readonly getSiteDeviceParam: "/power_service/v1/site/get_site_device_param";
+    /**
+     * POST (encrypted+signed): write a site "device param" block. Body is
+     * `{ site_id, cmd: 246, param_type, param_data: <JSON string> }`. Used for the SOC-limit write
+     * (`param_type "27"`, `param_data` = the SocSettingParam map) — see {@link SolixClient.setSafetySocParams}.
+     */
+    readonly setSiteDeviceParam: "/power_service/v1/site/set_site_device_param";
+};

package/dist/transport/media-failure.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Why acquiring a push thumbnail produced no bytes.
+ *
+ * Transport vocabulary, and it stays inside `transport/`: the modules that raise it and the cache that
+ * reads it are both here, and neither the device model nor the client names it. Nothing crosses the
+ * capability boundary, so nothing belongs in the shared floor.
+ *
+ * @module transport/media-failure
+ */
+/**
+ * The terms an acquisition failure is reported in — a CLOSED vocabulary, and that is the point.
+ *
+ * `download-failed` says a candidate did not become an image; it does not say whether the URL was
+ * refused before a packet moved, the host answered 404, the transfer timed out, or the bytes arrived
+ * and would not decode. Those need entirely different fixes, so the distinction has to survive to
+ * whatever is reading the log.
+ *
+ * It is a fixed vocabulary rather than an error message because the thing that fails holds a signed
+ * media URL and a response body, and neither may reach a log line. Every member here is a term this
+ * file defines; a downloader's own wording never is.
+ *
+ * - `url-not-allowed` — the candidate URL failed the media allowlist (scheme, credentials, port, a
+ *   literal address, or a host the SDK does not download from). Nothing was requested.
+ * - `address-not-public` — the host resolved to nothing, or to an address that is not public.
+ * - `redirect-not-allowed` — the media host redirected somewhere the object-store allowlist refuses,
+ *   redirected without a target, or redirected twice.
+ * - `http-status` — the host answered, with a status other than 200. Carried alongside as `status`.
+ * - `too-large` — the body exceeded the download bound, declared or observed.
+ * - `timeout` — the whole attempt, DNS included, outlived its window.
+ * - `network` — the request itself failed: connect, TLS, a reset mid-body.
+ * - `decode-failed` — the bytes arrived and the push-image decoder refused them. A property of the
+ *   image, not of the network.
+ */
+export type MediaFailureReason = "url-not-allowed" | "address-not-public" | "redirect-not-allowed" | "http-status" | "too-large" | "timeout" | "network" | "decode-failed";
+/** Every {@link MediaFailureReason}, so a tag that crossed an injected boundary can be checked against it. */
+export declare const MEDIA_FAILURE_REASONS: readonly MediaFailureReason[];
+/**
+ * The tag a media-acquisition failure carries for diagnostics.
+ *
+ * A property rather than a base class: the cache that logs it takes its downloader by injection and
+ * must not import the transport that throws — so it reads this shape off an unknown error and checks
+ * the term against {@link MEDIA_FAILURE_REASONS} before it goes anywhere near a log.
+ */
+export interface MediaFailure {
+    readonly mediaFailure: MediaFailureReason;
+    /** The HTTP status, when {@link mediaFailure} is `http-status`. */
+    readonly status?: number;
+}

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

@@ -3,3 +3,6 @@ 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";
+export { SOLIX_MODBUS_EMS_MODES } 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