@mega-yfue/eufy-sdk 0.0.4 → 0.1.0-beta.0

package/dist/core/crypto.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Eufy "mega" (Anker AIoT) cloud crypto — algo_ecdh.
+ *
+ * The full request scheme, reverse-engineered + verified against live traffic
+ * (2026-06). Three layers:
+ *
+ *  A. Key exchange (bootstrap, per region):
+ *       client_public_key = base64( IV(16) || AES-128-CBC(pubkeyHex, localKey) )
+ *       signed with HMAC-SHA256(localKey-hex-utf8, `${ts}+${once}+${encPubKey}`),
+ *       sending a client-generated X-Key-Ident. The server replies with its
+ *       public key, AES-CBC-encrypted the same way; ECDH(P-256) → shareKey
+ *       (first 32 hex chars of the shared secret).
+ *
+ *  B. Per-request body: base64( IV(16) || AES-128-CBC-PKCS7(plaintext) ),
+ *       key = shareKey[:16 bytes]. Response `data` decrypts the same way.
+ *
+ *  C. x-signature = HMAC-SHA256( shareKey-hex-utf8,
+ *                               [ts, once, encBody?].join("+") )  (hex).
+ *
+ * Layers B and C are verified byte-exact against a captured request
+ * (src/__tests__/crypto.spec.ts).
+ */
+import { type ECDH } from "node:crypto";
+export declare const P256 = "prime256v1";
+/**
+ * The eufy_mega app localKey — a single AES-128 key (hex) used to bootstrap the
+ * ECDH key exchange across the whole mega host stack (openapi + passport + app-*).
+ * Extracted from the iOS Mega app bundle.
+ */
+export declare const EUFY_MEGA_LOCAL_KEY_HEX = "2500a7d5617812f9d52515b2c8f20a3d";
+/**
+ * The **eufylife** data-host localKey — a SEPARATE AES-128 bootstrap key for the
+ * `security-app-{shard}.eufylife.com` gateway (faces, get_ciphers, commerce, geofence).
+ * That host runs its own ECDH key exchange at `/v3/openapi/oauth/key/exchange` and rejects
+ * the mega localKey. Identified by HMAC-matching a captured eufylife key-exchange signature.
+ */
+export declare const EUFYLIFE_LOCAL_KEY_HEX = "118c12c81e211149304bd70a0c071d01";
+/**
+ * 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).
+ */
+export declare const SERVER_STATIC_PUBLIC_KEY_HEX = "04c5c00c4f8d1197cc7c3167c52bf7acb054d722f0ef08dcd7e0883236e0d72a3868d9750cb47fa4619248f3d83f0f662671dadc6e2d31c2f41db0161651c7c076";
+/** 32-hex random id (uuid-without-dashes), for X-Key-Ident / X-Request-Once. */
+export declare function genId(): string;
+/** Unix seconds as a string (X-Request-Ts). */
+export declare function nowSec(): 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]). */
+export declare function aesKey(shareKeyHex: string): Buffer;
+/** HMAC sign key = the shareKey hex string itself, as UTF-8 bytes. */
+export declare function signKey(shareKeyHex: string): Buffer;
+/** Encrypt a body: base64( IV(16) || AES-128-CBC-PKCS7(plaintext) ). */
+export declare function encryptBody(plaintext: string | Buffer, shareKeyHex: string): string;
+/** Decrypt a base64( IV(16) || AES-128-CBC-PKCS7 ) body. */
+export declare function decryptBody(b64: string, shareKeyHex: string): Buffer;
+/**
+ * x-signature = HMAC-SHA256(signKey(shareKey), [ts, once, encBody?].join("+")).
+ * `encBody` is the ENCRYPTED body actually sent; omit for empty-body requests.
+ */
+export declare function signRequest(shareKeyHex: string, ts: string, once: string, encBodyB64?: string): string;
+/** A negotiated session: shareKey + the X-Key-Ident the client minted for it. */
+export interface SessionEntry {
+    keyIdent: string;
+    shareKey: string;
+    clientPublicKeyHex: string;
+    clientPrivateKeyHex: string;
+    createdAt: number;
+}
+export interface KeyExchangePrep {
+    ecdh: ECDH;
+    localKey: Buffer;
+    keyIdent: string;
+    /** base64 body to POST as { client_public_key }. */
+    encryptedClientPublicKey: string;
+    /** algo_ecdh headers for the key-exchange POST. */
+    headers: Record<string, string>;
+    clientPublicKeyHex: string;
+}
+/**
+ * Build a key-exchange request: an ephemeral P-256 keypair whose public hex is
+ * AES-128-CBC(localKey)-encrypted, signed with the localKey-hex as UTF-8.
+ */
+export declare function prepareKeyExchange(localKeyHex?: string): KeyExchangePrep;
+/**
+ * Finish the exchange: decrypt the server's AES-CBC-wrapped public key with the
+ * localKey, ECDH-derive, and take the first 32 hex chars as the shareKey.
+ */
+export declare function finishKeyExchange(prep: KeyExchangePrep, serverPublicKeyB64: string): SessionEntry;
+/**
+ * Encrypt the login password against the hardcoded server static public key.
+ * AES-256-CBC, key = full 32-byte ECDH secret, IV = its first 16 bytes.
+ * Returns the client pubkey hex (for client_secret_info.public_key) + b64 ct.
+ */
+export declare function encryptLoginPassword(password: string): {
+    clientPublicKeyHex: string;
+    encryptedPassword: string;
+};

package/dist/core/index.d.ts

@@ -1,7 +1,9 @@
-/**
- * Shared primitives: crypto, cross-layer contracts, value types, session store, logging, utilities.
- *
- * `core/` is the only layer both `model/` and `transport/` may depend on, which is what keeps the
- * two decorrelated.
- */
-export {};
+export * from "./crypto.js";
+export * from "./types.js";
+export * from "./contracts.js";
+export * from "./raw-dp-writer.js";
+export * from "./raw-dp-hex.js";
+export * from "./logger.js";
+export * from "./store.js";
+export * from "./util.js";
+export * from "./lz4-block.js";

package/dist/core/logger.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Pluggable diagnostics logging.
+ *
+ * The SDK emits internal diagnostics through a {@link Logger} a host supplies — so its logs flow
+ * into the host's own pipeline (tslog, winston, pino, …) with real log levels, instead of a hard-wired
+ * `console`. No logger supplied → {@link noopLogger} swallows everything (silent by default).
+ *
+ * The interface is a STRUCTURAL 4-level sink (`debug`/`info`/`warn`/`error`), shaped to match
+ * `console`, tslog, and winston natively; pino (object-first) plugs in via a one-line adapter:
+ * `{ logger: { debug: (m, ...a) => pino.debug(a[0] ?? {}, m), … } }`.
+ */
+/** Severity levels, low → high. */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Host-pluggable diagnostics sink. Pass one as `logger` when constructing `EufyMega`; the
+ * SDK calls the matching level method with a `[subsystem]`-prefixed message and optional args.
+ *
+ * @example
+ * ```ts
+ * // A custom sink (or pass a tslog / winston instance directly — they already match this shape):
+ * const eufy = new EufyMega({
+ *   logger: { debug: (m, ...a) => log.debug(m, ...a), info: () => {}, warn: console.warn, error: console.error },
+ * });
+ * ```
+ */
+export interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/** Discards everything. The default when no `logger` is supplied — the SDK is silent. */
+export declare const noopLogger: Logger;
+/**
+ * Built-in {@link Logger} that writes to `console`, gated by a minimum level. `new ConsoleLogger()`
+ * turns on all diagnostics; `new ConsoleLogger("warn")` shows only warnings and errors. Each level maps
+ * to the matching `console` method.
+ *
+ * @example
+ * ```ts
+ * const eufy = new EufyMega({ logger: new ConsoleLogger() });        // verbose
+ * const quiet = new EufyMega({ logger: new ConsoleLogger("warn") }); // warn + error only
+ * ```
+ */
+export declare class ConsoleLogger implements Logger {
+    private readonly minLevel;
+    constructor(minLevel?: LogLevel);
+    private enabled;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}

package/dist/core/lz4-block.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Decompressor for a raw LZ4 *block* — the form the map stream's pixel planes arrive in.
+ *
+ * The robot publishes its map over a second MQTT topic, and the pixel planes inside are compressed
+ * with LZ4 whenever that saves anything. There is no flag saying so: the message carries both the
+ * `pixels` bytes and a `pixel_size`, and **the two disagreeing IS the flag** — a plane that compressed
+ * to nothing useful is sent verbatim, with the two equal. So the caller decides, and passes the size
+ * it already has.
+ *
+ * **Why not an npm package.** What travels here is a bare LZ4 block: no magic number, no frame header,
+ * no checksum, no stored size. Every LZ4 package on npm speaks the *frame* format by default and
+ * exposes the block API awkwardly if at all, and the block format itself is one loop over four
+ * quantities. A dependency would be more code to audit than the sixty lines here, so this is
+ * hand-written and tested against blocks produced by the reference liblz4 implementation.
+ *
+ * @module core/lz4-block
+ */
+/**
+ * Decompress an LZ4 block into exactly `size` bytes, or `undefined` if the block is malformed.
+ *
+ * **Every failure is `undefined`, and the length check is what makes that trustworthy.** A truncated or
+ * corrupt block does not fail loudly on its own — LZ4 has no checksum and no terminator, so a mangled
+ * block usually just stops producing output early, and a decompressor that returned what it had would
+ * hand back a plausible, short, wrong map. Requiring the output to reach `size` exactly turns that into
+ * a rejection, and it costs nothing: the caller already knows the size, which is how it knew to call.
+ *
+ * The other rejections are the reads that would otherwise wander: a length that runs off the end of the
+ * block, a back-reference pointing before the start of the output or nowhere at all, and a match that
+ * would overrun `size`.
+ *
+ * Matches may overlap their own output — an offset of 1 with a length of 200 is how a run of one
+ * repeated byte is encoded, and it is the common case in a mostly-empty map. That is why the copy below
+ * is a byte-at-a-time loop and not a block copy: the bytes it reads are ones it just wrote.
+ */
+export declare function lz4BlockDecompress(block: Uint8Array, size: number): Buffer | undefined;

package/dist/core/raw-dp-hex.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The Raw-DP frame, arriving hex-encoded instead of base64.
+ *
+ * A robot publishes its map to a second MQTT topic — `biz/eufy_home/<model>/<sn>/res` — and the
+ * payloads there are the SAME `varint(len) ++ protobufMessage` frame every Raw DP carries, wrapped in
+ * a JSON envelope and written as hex rather than base64. So the whole reader already exists: only the
+ * outer encoding differs, and this turns one into the other.
+ *
+ * Deliberately not a second codec. `RawDpCodec` owns the framing, the length-prefix validity check and
+ * the wire-type walk; re-implementing any of that for a different string encoding would be two readers
+ * to keep in agreement, which is how they stop agreeing.
+ *
+ * @module core/raw-dp-hex
+ */
+/**
+ * Hex the biz stream carries, re-encoded as the base64 a {@link RawDpCodec} reads — or `undefined`
+ * when the input is not clean hex.
+ *
+ * **The validation is the point, and it is not paranoia.** `Buffer.from(s, "hex")` never throws: it
+ * decodes until it meets a character that is not a hex digit and silently returns what it got, and it
+ * drops a trailing half-byte from an odd-length string. For base64 that silent truncation is harmless,
+ * because the codec's length prefix will not match the shortened body and the payload is rejected —
+ * the reader's own doc says so. Hex breaks that guarantee: truncation removes bytes from the END,
+ * so `"02" + "aabb" + <garbage>` decodes to a prefix of 2 followed by exactly two bytes, passes the
+ * length check, and hands back a message with the garbage quietly discarded. A shorter,
+ * self-consistent, WRONG payload is the one failure the codec cannot catch for us, so it is caught
+ * here instead.
+ *
+ * An empty string is `undefined` rather than an empty frame: the envelope omits the field entirely
+ * when there is nothing to send, so "" means "no payload", not "a payload of no bytes".
+ */
+export declare function hexToRawDp(hex: string): string | undefined;

package/dist/core/raw-dp-writer.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Writer for the structured, base64-encoded values some device data points carry in place of a plain
+ * scalar — the mirror of the `RawDpCodec` reader in `./contracts.ts`.
+ *
+ * Hand-rolling a write's bytes is where silent wire bugs come from, and the nesting gets deep fast: a
+ * dock command wraps a `oneof` two levels deep, a clean-parameter write nests three, and a room-select
+ * carries a repeated sub-message. On a fire-and-forget write, a bad frame is indistinguishable from
+ * success.
+ *
+ * **What this is not.** It is not a protobuf library and does not want to be. There is no schema, no
+ * field-name lookup, no wire-type inference from a declared type: the caller states the field number and
+ * the shape, exactly as the reader states the field number it wants back. That keeps the model layer
+ * free of `protobufjs` (an architecture rule, not a preference — the model layer may not take transport
+ * dependencies) and keeps the whole encoder small enough to read in one sitting.
+ *
+ * **Framing.** {@link RawDpWriter.finish} emits `varint(bodyLength) ++ body`, base64-encoded — the same
+ * envelope `RawDpCodec.decode` expects, which is what makes a round-trip through the two a real test.
+ *
+ * @module core/raw-dp-writer
+ */
+/**
+ * Encode an unsigned integer as a base-128 varint, low group first with the continuation bit set on
+ * every group but the last.
+ *
+ * Takes a `number` and rejects anything that is not a non-negative safe integer, rather than silently
+ * truncating: JavaScript's bitwise operators are 32-bit, so a naive shift-based loop wraps above 2³¹
+ * and would emit a plausible-looking frame for the wrong value. Division keeps the full safe-integer
+ * range available and the guard makes the boundary explicit instead of surprising.
+ */
+export declare function encodeVarint(value: number): number[];
+/**
+ * ZigZag-encode a signed integer, mapping small negatives onto small unsigned values so a `sint32`
+ * costs one byte rather than ten.
+ *
+ * The clean line needs this for map coordinates, which are signed centimetres and routinely negative —
+ * a robot sent to a point encoded as a plain varint goes somewhere real and wrong. Kept separate from
+ * {@link encodeVarint} because the choice belongs to the field's declared type, which only the caller
+ * knows: `int32` and `sint32` are the same wire type and encode the same number differently.
+ */
+export declare function zigzag(value: number): number;
+/**
+ * Builds one protobuf message body, field by field.
+ *
+ * A field's number and shape are given at the call site, which is the same contract the reader offers in
+ * reverse. Nothing here validates that a field number suits the message being built — this layer does
+ * not know what message that is, and the capability that does states it in its own field-number table.
+ *
+ * **Zero-valued fields are the caller's decision, not this writer's.** proto3 omits them by default and
+ * a device reads an absent field as its zero, so emitting `0` explicitly and omitting it usually mean
+ * the same thing — but not always, and only the capability knows which. {@link int} therefore writes
+ * exactly what it is given, and omitting the call is what leaves the field absent.
+ */
+export declare class RawDpWriter {
+    private readonly body;
+    /** A varint-valued field (`int32`, `uint32`, `bool`, an enum member). */
+    int(field: number, value: number): this;
+    /** A signed varint field (`sint32`, `sint64`), ZigZag-encoded — see {@link zigzag}. */
+    sint(field: number, value: number): this;
+    /** A boolean field, on protobuf's own terms: `1` or `0` in a varint. */
+    bool(field: number, value: boolean): this;
+    /** A length-delimited field carrying raw bytes — a string, a blob, or a message built elsewhere. */
+    bytes(field: number, value: Uint8Array | readonly number[]): this;
+    /**
+     * A nested sub-message, built by `build` into a writer of its own.
+     *
+     * The sub-message is emitted even when `build` writes nothing into it. That is not an oversight: an
+     * EMPTY sub-message is how these protocols say "this subsystem exists and is in its zero state", as
+     * opposed to saying nothing about it, and the readers on the other side of this file depend on the
+     * distinction. Omitting the call is what says nothing about it.
+     */
+    sub(field: number, build: (w: RawDpWriter) => void): this;
+    /** The message body on its own, unframed — for nesting into another writer. */
+    toBytes(): readonly number[];
+    /**
+     * The finished DP value: `varint(bodyLength) ++ body`, base64-encoded.
+     *
+     * This is the envelope `RawDpCodec.decode` unwraps, so a value produced here and read back through the
+     * codec is a genuine round-trip rather than two implementations of the same guess.
+     */
+    finish(): string;
+}
+/** Build a DP value in one expression: `rawDp((w) => w.int(1, 6).int(2, seq))`. */
+export declare function rawDp(build: (w: RawDpWriter) => void): string;

package/dist/core/store.d.ts

@@ -0,0 +1,43 @@
+import type { RegionShard } from "../transport/http/mega-client.js";
+/**
+ * The persisted session record. Internal shape — a host supplies a `SessionStore`, never builds this.
+ * @internal
+ */
+export interface PersistedSession {
+    userId: string;
+    authToken: string;
+    geoKey?: string;
+    region: RegionShard;
+    openudid: string;
+    /** This install's reported device model + media user-agent, generated once and reused. */
+    phoneModel?: string;
+    mediaUserAgent?: string;
+    /** ECDH session: shareKey hex (32 chars) + the bound key-ident. */
+    shareKey: string;
+    keyIdent: string;
+    /** Unix seconds when the auth token expires (0 = unknown). */
+    tokenExpiresAt: number;
+    savedAt: number;
+}
+export interface SessionStore {
+    load(): PersistedSession | null;
+    save(s: PersistedSession): void;
+    clear(): void;
+}
+/** In-memory store (no persistence) — the default. */
+export declare class MemorySessionStore implements SessionStore {
+    private s;
+    load(): PersistedSession | null;
+    save(s: PersistedSession): void;
+    clear(): void;
+}
+/** JSON-file store, e.g. new FileSessionStore("./.eufy-session.json"). */
+export declare class FileSessionStore implements SessionStore {
+    private readonly path;
+    constructor(path: string);
+    load(): PersistedSession | null;
+    save(s: PersistedSession): void;
+    clear(): void;
+}
+/** A persisted session is usable if it has a token that isn't (near-)expired. */
+export declare function isSessionValid(s: PersistedSession | null, skewSec?: number): boolean;

package/dist/core/types.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Unified device + transport model.
+ *
+ * One package, every eufy device class. Two things vary per device and are
+ * abstracted here so the rest of the code never branches on device kind:
+ *
+ *   API backend   — how we talk to the cloud:
+ *     - 'mega'     : the v6 Anker AIoT API (algo_ecdh signed bodies). Used for EVERY device —
+ *                    appliances/lights/vacuums AND cameras/HomeBases/sensors (device list, dsk,
+ *                    ciphers, faces, events). This is the only backend the SDK uses.
+ *     - 'legacy'   : the classic pre-v6 eufy security API. NOT used by this
+ *                    SDK (v6 migrated everything to mega); kept for reference/old apps.
+ *
+ *   Realtime transport — how live state/commands flow:
+ *     - 'smqtt'    : secure Anker MQTT broker (mTLS, aiot-mqtt-*.anker.com:8883).
+ *     - 'p2p'      : peer-to-peer ThroughTek PPCS (LAN-direct/relay) — cameras. (eufy's own leo_rtc
+ *                    WebRTC is a separate stack used only by newer NVR-class devices.)
+ *
+ * A device declares which it uses; the facade routes accordingly.
+ */
+/**
+ * Names the wire backends a device is reachable on — transport vocabulary, not a host concern.
+ * @internal
+ */
+export type ApiBackend = "mega" | "legacy" | "ankermake";
+export type RealtimeKind = "smqtt" | "p2p" | "ankermake-mqtt";
+/**
+ * The device `category` strings that mark a 3D printer (ankermake plane). Defined once here — the model
+ * layer's codec classifier reads THIS rather than restating the literal, so widening it can't leave the
+ * two deciders disagreeing (the dependency rule only allows sharing in this direction).
+ */
+export declare const PRINTER_CATEGORY_RE: RegExp;
+/**
+ * The coarse device grouping. Every value is one the SDK can actually DERIVE from a
+ * resolved codec — anything the codec space doesn't confidently name lands in `"other"` rather than a
+ * guess. Intentionally coarse: the precise kind is named by the capabilities.
+ */
+export type DeviceClass = "camera" | "homebase" | "vacuum" | "mower" | "sensor" | "light" | "printer" | "other";
+/** Normalised device record, regardless of which API produced it. */
+export interface EufyDevice {
+    sn: string;
+    name?: string;
+    model: string;
+    /** Anker category string: eufy_security | eufy_mega | eufy_home … */
+    category: string;
+    deviceClass: DeviceClass;
+    /** Which cloud API owns this device. */
+    api: ApiBackend;
+    /** Which realtime transport carries its live state/commands. */
+    realtime: RealtimeKind;
+    /**
+     * The station this device's traffic belongs to: its parent HomeBase, or its own serial when it has none.
+     *
+     * `parent_sn` carries the parent on an attached device. `station_sn` is frequently absent there — empty on
+     * every attached sensor of a T8010 — and serves only as a fallback for a device naming no parent.
+     */
+    stationSn?: string;
+    /** Present (and non-empty) for P2P devices. */
+    p2pDid?: string;
+    /**
+     * Device state data points (param_type → param_value), exactly as the cloud record carries them.
+     * Raw and unnamed: the capability surface resolves these into named properties. `Device.inspect`
+     * labels them for troubleshooting.
+     *
+     * **Not a realtime source.** These are refreshed server-side on the device's own cloud heartbeat,
+     * which is slow: measured across a live fleet, the freshest param on an active device was ~12 minutes
+     * old, and the per-device `get_device_param_list` call returns the same staleness as the bulk list
+     * (so fetching harder does not make them fresher). They are a coarse state snapshot plus liveness
+     * evidence ({@link paramUpdatedAt}); realtime state arrives over push / P2P / MQTT.
+     */
+    params?: Record<number, string>;
+    /**
+     * When each param in {@link params} was last written server-side (`param_type` → **unix SECONDS**,
+     * the wire's own `update_time` unit — not milliseconds). The device heartbeats its params up to the
+     * cloud, so these are the freshest liveness evidence available without opening a transport.
+     *
+     * Sparse by construction: a param the record delivered without an `update_time` has no entry here.
+     */
+    paramUpdatedAt?: Record<number, number>;
+    /**
+     * The most recent {@link paramUpdatedAt} across all of this device's params, in **milliseconds**
+     * (comparable to `Date.now()` directly). `undefined` when the record carried no timestamp at all.
+     *
+     * This is an observation — "the device last reported at T" — deliberately **not** a reachability
+     * verdict. How long a silence means "unreachable" depends on the device (a mains camera heartbeats
+     * constantly; a battery sensor may be quiet for days by design), so the threshold is the caller's to
+     * choose; the SDK reports the fact.
+     */
+    lastSeenMs?: number;
+    /** Raw record from the source API, for fields not yet normalised. */
+    raw?: unknown;
+}
+/** A realtime message normalised across transports. */
+export interface RealtimeMessage {
+    deviceSn?: string;
+    topic?: string;
+    raw: unknown;
+}
+/** A vendor-authored availability state, distinct from inferred reachability or transport lifecycle. */
+export type AvailabilityState = "available" | "unavailable";
+/**
+ * Provenance of an authoritative availability observation. The current contract contains only the
+ * secure-MQTT signal whose polarity and device attribution are established by the current vendor app.
+ */
+export type AvailabilitySource = {
+    readonly transport: "smqtt";
+    readonly signal: "state-info";
+};
+/**
+ * An explicit availability observation whose entity, polarity and scope are verified on the current
+ * vendor wire. The SDK emits this only for authoritative signals; silence, stale cloud facts, failed
+ * operations and idle transports do not create or clear one.
+ */
+export interface AvailabilityObservation {
+    readonly entity: {
+        readonly kind: "device";
+        readonly sn: string;
+    };
+    readonly availability: AvailabilityState;
+    readonly source: AvailabilitySource;
+    readonly scope: "device";
+    /** Vendor-supplied observation time in milliseconds, when the envelope carries one. */
+    readonly observedAt?: number;
+    /** Vendor-supplied message ordering value, when the envelope carries one. */
+    readonly sequence?: number;
+    /** When the SDK received this explicit signal, in milliseconds. */
+    readonly receivedAt: number;
+}
+/**
+ * Common surface for every realtime transport (smqtt / p2p).
+ * Implementations live under src/mqtt and src/p2p; the facade owns selection.
+ */
+export interface RealtimeTransport {
+    readonly kind: RealtimeKind;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    subscribeDevice(device: EufyDevice): Promise<void>;
+    /** Publish a command body to a device topic (the `/req` direction). */
+    publish(topic: string, body: string | Buffer, opts?: {
+        qos?: 0 | 1 | 2;
+    }): Promise<void>;
+    on(event: "connect", listener: () => void): this;
+    on(event: "disconnect", listener: (reason?: unknown) => void): this;
+    on(event: "message", listener: (msg: RealtimeMessage) => void): this;
+    on(event: "error", listener: (err: Error) => void): this;
+}
+/**
+ * Map a device's category to its API backend + realtime transport.
+ *
+ * Deliberately does NOT classify the device itself. Which *kind* of thing a record is depends on the
+ * eufy `DeviceType` space, which grows with every product launch — that knowledge lives in `model/`
+ * (`codecForType`, where camera is the residual bucket so a new SKU needs no edit), and duplicating a
+ * list of ids here would mean editing the leaf layer on every release. The client derives
+ * {@link EufyDevice.deviceClass} from the resolved codec instead.
+ *
+ * The security ecosystem (cameras / HomeBases / sensors) is `p2p`: v6 serves its cloud side through
+ * the SAME mega (`algo_ecdh`) API as everything else — device list, dsk, ciphers, faces, events — but
+ * its realtime is P2P plus push, never MQTT. A `p2p_did` alone is sufficient evidence, since only that
+ * ecosystem is issued one. Everything else is a mega/home appliance on Anker secure MQTT.
+ *
+ * Internal classification helper; `Device` carries the resolved result.
+ * @internal
+ */
+export declare function classifyDevice(raw: {
+    category?: string;
+    device_model?: string;
+    p2p_did?: string;
+    device_type?: number;
+} & Record<string, unknown>): Pick<EufyDevice, "api" | "realtime" | "category">;

package/dist/core/util.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Small shared utilities used across the SDK.
+ */
+/**
+ * A restartable single-shot timer — the arm / cancel / re-arm pattern the P2P lifecycle repeats in
+ * several places (session idle-detach, stream linger, battery budget + its grace, the warm-up
+ * deadline). {@link arm} (re)schedules, replacing any pending fire; {@link cancel} clears it; the
+ * handle clears itself right before firing so {@link pending} reads `false` inside the callback. The
+ * timer is `unref`'d so a pending fire never keeps the process alive.
+ */
+export declare class Timer {
+    private handle?;
+    /** (Re)arm to run `fn` after `ms`, cancelling any already-pending fire. */
+    arm(ms: number, fn: () => void): void;
+    /** Cancel a pending fire. No-op if not armed. */
+    cancel(): void;
+    /** Whether a fire is currently scheduled. */
+    get pending(): boolean;
+}
+/**
+ * Exhaustiveness guard for discriminated unions. Placed in a `switch` `default` (or the else of an
+ * `if`-chain) over every variant: if a new variant is added and left unhandled, the call fails to
+ * typecheck (its type is no longer `never`), and at runtime it throws instead of silently falling
+ * through.
+ */
+export declare function assertNever(value: never): never;
+/**
+ * Coerce a property value to a boolean WITHOUT the `Boolean("false") === true` footgun (every
+ * non-empty string — including `"false"` and `"0"` — is truthy under `Boolean()`). Only an explicit
+ * `true` / `1` / `"1"` / `"true"` (case-insensitive) enables; everything else is `false`.
+ */
+export declare function asBool(value: unknown): boolean;
+/**
+ * Round to an integer and clamp into `[min, max]`. For scalar device params that take a bounded int
+ * (volume/brightness/color-temp 0..100, etc.), dispatched fire-and-forget — a non-numeric or
+ * out-of-range input must never reach the wire as-is. NaN input (e.g. `Number("x")`) fails safe to
+ * `min`: `Math.max`/`Math.min` propagate NaN rather than ignoring it, so that has to be checked
+ * explicitly, not relied on implicitly.
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Order-insensitive deep structural equality. Used for change detection over decoded param values
+ * (`boolean | number | string | object | array`): a re-serialized param whose object keys come back
+ * in a different order must NOT read as "changed" (a `JSON.stringify` compare is key-order sensitive
+ * and flaps). Primitives compare with `Object.is` (so `NaN === NaN`, `+0 !== -0`); arrays compare
+ * length then elementwise; plain objects compare the same key set recursively; anything else
+ * (functions, class instances, Buffers, …) falls back to `Object.is`.
+ */
+export declare function structuralEqual(a: unknown, b: unknown): boolean;
+/**
+ * Coerce `value` to one of the numeric values of a fixed enum-object (e.g. `Watermark`,
+ * `HubAlarmTone`, `DoorbellRingtone`), or `undefined` if it isn't one. Unlike `clamp` (for a
+ * continuous range), an enum has a small fixed set of real options — silently rounding/clamping a bad
+ * index to the nearest valid one would send a WRONG-but-plausible value on a fire-and-forget write,
+ * not a safe default. Anything outside the set is rejected instead.
+ */
+export declare function coerceEnumValue(enumObj: Record<string, number>, value: unknown): number | undefined;
+/** The valid values of an enum-object, `/`-joined — for the "not a valid option (valid: 0/1/2)" errors. */
+export declare function enumValues(enumObj: Record<string, number>): string;
+/**
+ * Invert an enum-object (`name → wire value`) into the `raw → label` form a published option set
+ * takes, so a named set is declared ONCE — as the enum callers write against — and the published
+ * domain cannot drift from it.
+ */
+export declare function enumLabels(enumObj: Readonly<Record<string, number>>): Record<number, string>;
+/**
+ * Parse `text` as a JSON object, or `undefined` on any failure — never throws. Shared by the MQTT
+ * and Tuya transport layers; sits here so each module doesn't define its own copy.
+ */
+export declare function jsonObject(text: unknown): Record<string, unknown> | undefined;
+/** 16-bit unsigned, little-endian. */
+export declare function u16le(n: number): Buffer;
+/** 16-bit unsigned, big-endian. */
+export declare function u16be(n: number): Buffer;
+/** 32-bit unsigned, little-endian. */
+export declare function u32le(n: number): Buffer;
+/** 32-bit unsigned, big-endian. */
+export declare function u32be(n: number): Buffer;

package/dist/index.d.ts

@@ -1,13 +1,10 @@
 /**
- * Public entry point of the SDK.
+ * eufy-sdk — one typed client for every Anker eufy device.
  *
- * The library is split into four layers, each behind its own barrel. `model/` and `transport/` are
- * decorrelated by design — neither imports the other, and anything genuinely shared between them is
- * a contract in `core/`. `client/` is the facade a caller actually holds.
- *
- * The layers are empty in this scaffold commit; the implementation lands with the source move.
+ * Log in, model devices as capability-driven objects with a fluent typed API,
+ * and subscribe to typed semantic events. Transport is internal.
  */
+export * from "./client/index.js";
 export * from "./core/index.js";
 export * from "./transport/index.js";
 export * from "./model/index.js";
-export * from "./client/index.js";