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

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

@@ -0,0 +1,107 @@
+/**
+ * Secure MQTT ("smqtt") — Anker AIoT broker, mutual-TLS.
+ *
+ * Broker: mqtts://aiot-mqtt-{region}.anker.com:8883. Credentials come from the
+ * mega API `get_user_mqtt_info` call: a per-user client certificate + RSA key,
+ * and a server CA (the `aws_root_ca1_pem` field, despite the name, is a GoDaddy
+ * root). The default clientId is the cert CN = `{user_id}-{app_name}`.
+ *
+ * Topic vocabulary and the per-line credential scope live in `./topics.ts` — publish to `/req`
+ * (cloud→device commands), subscribe to whichever inbound legs that line uses. Granted for eufy_mega +
+ * eufy_home devices; eufy_security (cameras) are DENIED here (they use P2P) — see src/types.ts
+ * classifyDevice.
+ */
+import { EventEmitter } from "node:events";
+import type { EufyDevice, RealtimeTransport } from "../../core/types.js";
+import { type Logger } from "../../core/logger.js";
+/**
+ * Per-user mTLS credentials as returned by get_user_mqtt_info.
+ *
+ * Broker credentials as the cloud returns them — internal transport detail.
+ * @internal
+ */
+export interface SecureMqttCredentials {
+    /** Broker host, e.g. aiot-mqtt-eu.anker.com (port assumed 8883). */
+    endpoint_addr: string;
+    endpoint_port?: number;
+    /** PEM client certificate (CN = {user_id}-{app_name}). */
+    certificate_pem: string;
+    /** PEM client private key. */
+    private_key: string;
+    /** PEM server CA (field is misleadingly named aws_root_ca1_pem — it's a GoDaddy root). */
+    aws_root_ca1_pem: string;
+    /** Default clientId (cert CN = thing_name). */
+    thing_name?: string;
+    /** App scope the cert is granted for (the `{app_name}` topic segment) — e.g. `eufy_mega`. */
+    app_name?: string;
+    /** The account/user id the cert is bound to. */
+    user_id?: string;
+}
+/**
+ * Construction options for the internal broker client.
+ * @internal
+ */
+export interface SecureMqttOptions {
+    credentials: SecureMqttCredentials;
+    clientId?: string;
+    /** Dial this IP directly instead of resolving `credentials.endpoint_addr` via DNS — the broker
+     * hostname fronts multiple independent backend instances that do NOT share subscribe/publish
+     * routing (see `transport/mqtt/broker-discovery.ts`); pin to the instance a device's session was
+     * confirmed to be on, found via {@link discoverReachableInstance}. */
+    instanceIp?: string;
+    /**
+     * mqtt.js's own `reconnectPeriod` (ms) — auto-reconnect on an unexpected drop. Default `5000`,
+     * right for the one long-lived connection (the facade's auto-started `this.transport`). A **one-shot**
+     * connection (opened for a single command, torn down right after — see `MqttCommandRouter.ensureSecurityMqttFor`)
+     * must pass `0` here: with a nonzero period, a connect that never establishes (or drops right after)
+     * leaves the underlying mqtt.js client retrying against that instance forever, orphaned in the
+     * background — {@link SecureMqtt.connect} rejecting/resolving doesn't stop it, only `end()` does, and
+     * a one-shot caller has no reason to ever call `end()` again after its one command is done.
+     */
+    reconnectPeriod?: number;
+    /** Diagnostics sink. Omit for silence. */
+    logger?: Logger;
+}
+/**
+ * The broker client. Internal transport; a host reaches appliances through the capability surface.
+ * @internal
+ */
+export declare class SecureMqtt extends EventEmitter implements RealtimeTransport {
+    readonly kind: "smqtt";
+    private client?;
+    private readonly o;
+    private readonly logger;
+    constructor(opts: SecureMqttOptions);
+    get id(): string;
+    /**
+     * Open the broker connection, resolving once it is established. Pinned to a broker instance's IP, or
+     * to the plain hostname; only the former needs its own TLS shape, see `./bare-ip-tls.ts`.
+     */
+    connect(): Promise<void>;
+    /**
+     * Subscribe every inbound leg this device's line uses (see `topics.ts` — one `/res` for most lines,
+     * 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
+     * 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>;
+    /**
+     * 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
+     * broker acks). This is the outbound leg — commands, alongside the receive-only `/res` subscriptions.
+     *
+     * NOTE: which cert scope is used does NOT gate publishing to a security device's topic — confirmed
+     * live, an `eufy_mega`-scoped cert and an `eufy_security`-scoped cert get the identical grant/deny
+     * pattern. What actually matters is landing on the broker instance that currently holds the device's
+     * session (`ensureSecurityMqttFor`/`broker-discovery.ts` — the NLB fronts several instances that
+     * don't share subscribe/publish routing).
+     */
+    publish(topic: string, body: string | Buffer, opts?: {
+        qos?: 0 | 1 | 2;
+    }): Promise<void>;
+    disconnect(): Promise<void>;
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Anker secure-MQTT topic vocabulary + the per-line credential scope.
+ *
+ * Two facts about this broker drive everything here, both CONFIRMED live (2026-07-28) against a real
+ * `eufy_life` light and cross-read from the disassembled V6 app
+ * (`com.anker.esiotkit.security_device.mqtt.SecurityMqttConstant`, `mqtt_serve.dart`):
+ *
+ *  - **The device→app leg is not `/res` for every line.** `eufy_life` reports land on `/app/res`;
+ *    the app subscribes four topics per light device and `/res` carries nothing. Other lines use
+ *    `/res` alone.
+ *  - **The topic space is partitioned by credential.** `get_user_mqtt_info` returns a DIFFERENT
+ *    certificate per `app-name`, and the AWS IoT policy granting `eufy_life/...` is attached only to
+ *    the `eufy_life` cert. Subscribing to a light's topics with the default credential is *silently*
+ *    denied — the broker answers SUBACK with a 128 grant rather than rejecting, which is why this
+ *    produced total silence instead of an error.
+ *
+ * Scope is derived from `EufyDevice.category` — a device-record field, not a capability — so this
+ * stays on the transport side of the capability↔transport boundary.
+ */
+import type { EufyDevice } from "../../core/types.js";
+/**
+ * Which `get_user_mqtt_info` credential a device's realtime traffic rides on. `"default"` is the
+ * headerless credential (observed `eufy_mega`-scoped) that serves every non-life MQTT device.
+ *
+ * A scope exists only where a DISTINCT credential does. `eufy_life` is one because its topic space is
+ * denied to the default credential. The Clean line (`eufy_home`) is NOT: its
+ * `cmd/eufy_home/<model>/<sn>/res` subscribe is confirmed against a T2351 on the
+ * default credential, which is the only one `get_user_mqtt_info` was ever asked for. Giving it a scope
+ * of its own would open a second connection under the SAME `thing_name` — AWS IoT treats a duplicate
+ * client id as a takeover and evicts the incumbent, so both lines would flap.
+ */
+export type MqttScope = "default" | "eufy_life";
+/**
+ * The credential scope a device's topics are granted under. Derived from `EufyDevice.category` — a
+ * device record field, not a capability — so this stays on the transport side of the boundary.
+ */
+export declare function mqttScopeFor(device: EufyDevice): MqttScope;
+/**
+ * The `app-name` request header value for a scope, or `undefined` for the default (headerless)
+ * credential — matching the optional argument of `getUserMqttInfo`.
+ */
+export declare function mqttAppName(scope: MqttScope): string | undefined;
+/**
+ * Build a topic for a device: `cmd/<prefix>/<model>/<sn>/<req|res>`. `leg` is required — the two
+ * directions are one word apart and publishing to the wrong one fails silently. The prefix is
+ * derived by the module-local `topicPrefix` — `eufy_home` for clean-line devices, `device.category` elsewhere.
+ */
+export declare function secureTopic(device: EufyDevice, leg: "req" | "res"): string;
+/**
+ * Every topic to subscribe for a device's inbound traffic.
+ *
+ * `eufy_life` (smart lights) gets the app's full four-topic set: `/app/res` (the state channel),
+ * `/res` (present in the app's subscribe list but observed to carry nothing on this line),
+ * `synq/…/state_info` (online/offline), and `/app/ota/res` (OTA progress).
+ *
+ * Clean-line devices (vacuum/mower) subscribe four topics on the `eufy_home` prefix:
+ *   - `cmd/…/res` — device→app DP reports and command replies (confirmed live on T2351)
+ *   - `biz/…/res` — cloud→app business-layer responses (TopicManager.getBizReqTopic())
+ *   - `biz/…/req` — cloud ACKs for app→cloud business requests (subscribe for ACKs)
+ *   - `dt/…/param_info` — device-twin parameter push
+ *
+ * Every other line subscribes `/res` alone.
+ */
+export declare function subscribeTopics(device: EufyDevice): readonly string[];
+/** A parsed inbound topic. `tail` is everything after the serial (`res`, `app/res`, `state_info`, …). */
+export interface ParsedTopic {
+    root: string;
+    category: string;
+    model: string;
+    sn: string;
+    tail: string;
+}
+/**
+ * Split an inbound topic into its parts. All roots this broker uses (`cmd/…`, `synq/…`, `biz/…`,
+ * `dt/…`) put the serial at index 3 regardless of how deep the tail runs, so the serial is read
+ * positionally rather than from the end — `…/<sn>/app/res` and `…/<sn>/app/ota/res` would otherwise
+ * yield the tail segment as the device id. Returns `undefined` on any shape this doesn't recognise,
+ * so an unparsed topic leaves `deviceSn` unset instead of carrying a guess.
+ */
+export declare function parseSecureTopic(topic: string): ParsedTopic | undefined;

package/dist/transport/p2p/adts.d.ts

@@ -0,0 +1,91 @@
+/**
+ * ADTS (Audio Data Transport Stream) helpers — the framing the device expects on the audio path a
+ * host pushes toward a camera. A host hands over an arbitrarily-chunked byte stream (an encoder's
+ * stdout, a file read), so frame boundaries have to be RECOVERED from the stream rather than assumed
+ * to align with the chunks; this is the single place that scans for them.
+ *
+ * An ADTS frame is a 7-byte header (9 with CRC) followed by the raw audio payload, and the header's
+ * own `frameLength` field spans header + payload — so the scan is self-delimiting once synced.
+ * Header layout, MSB-first, as the V6 app writes it (`media/player/audio/AacEncode.java:43-51`):
+ *
+ * ```
+ * byte 0     1111 1111   syncword high
+ * byte 1     1111 iilp   syncword low · i=MPEG version+layer · p=1 ⇒ NO CRC (2 fewer header bytes)
+ * byte 2     ppff ffpc   p=profile-1 · f=sampling-frequency index · c=channel-config high bit
+ * byte 3     cc.. LLL    c=channel-config low 2 bits · L=frameLength bits 12..11
+ * byte 4     LLLL LLLL   frameLength bits 10..3
+ * byte 5     LLLb bbbb   frameLength bits 2..0 · b=buffer fullness high
+ * byte 6     bbbb bbnn   buffer fullness low · n=frames-in-block minus one
+ * ```
+ *
+ * The device's parameters are fixed and verified against the app's own encoder configuration
+ * (`AacEncode.java:23-41`, `player/audio/BDBAudioConfig.java:6-66`): AAC-LC, 16 kHz, mono. One AAC-LC
+ * frame is 1024 samples, so at 16 kHz each frame carries exactly 64 ms of audio — the cadence the
+ * send side paces on.
+ *
+ * @module p2p/adts
+ */
+/** Samples per AAC-LC frame — fixed by the codec, not by these parameters. */
+export declare const AAC_SAMPLES_PER_FRAME = 1024;
+/** Sample rate the device's audio path runs at. */
+export declare const AAC_SAMPLE_RATE = 16000;
+/**
+ * Duration one frame represents, in milliseconds — `1024 / 16000`, exactly 64 ms. The send side both
+ * paces on this and steps its frame timestamp by it.
+ */
+export declare const AAC_FRAME_MS: number;
+/**
+ * Largest frame the device accepts. The app drops anything longer before it reaches the wire
+ * (`media/recorder/recorder/BDBRawAudioRecorder.java:98`), so a longer frame is a caller bug rather
+ * than something to split or truncate.
+ */
+export declare const MAX_AUDIO_FRAME_BYTES = 640;
+/** Parsed fields of one ADTS header, with the payload it introduces. */
+export interface AdtsHeader {
+    /** Header + payload length, as declared by the header itself. */
+    frameLength: number;
+    /** Bytes of header ahead of the payload — 7 without a CRC, 9 with one. */
+    headerLength: number;
+    /** Profile field, `1` for AAC-LC. */
+    profile: number;
+    /** Index into the ADTS sampling-frequency table, `8` for 16 kHz. */
+    frequencyIndex: number;
+    /** Channel configuration, `1` for mono. */
+    channels: number;
+}
+/**
+ * Read an ADTS header at `offset`, or `undefined` when the bytes there are not a plausible header —
+ * no syncword, a `frameLength` shorter than its own header, or not enough bytes to decide. Says
+ * nothing about whether the frame's payload has arrived yet; that is the scanner's job.
+ */
+export declare function parseAdtsHeader(buf: Buffer, offset?: number): AdtsHeader | undefined;
+/**
+ * Whether a header describes the audio parameters the device's path is fixed at — AAC-LC, 16 kHz,
+ * mono. A stream at any other rate or channel count is rejected rather than resampled: the device has
+ * no way to be told otherwise, so passing it through would produce audio at the wrong pitch and speed.
+ */
+export declare function isSupportedAdts(h: AdtsHeader): boolean;
+/**
+ * Human-readable reason a header is unsupported, for the error a caller sees. Reports the decoded
+ * values so a mis-configured encoder is obvious from the message alone.
+ */
+export declare function describeAdts(h: AdtsHeader): string;
+/**
+ * Incremental ADTS frame scanner. Feed it byte chunks in arrival order and it yields whole frames,
+ * holding a partial frame across calls — which is the whole point: a host's chunk boundaries have no
+ * relationship to frame boundaries, and a naive per-chunk parse would either split frames or resync
+ * mid-payload and emit garbage.
+ *
+ * A byte run that does not begin with a syncword is skipped one byte at a time until one is found, so
+ * a stream that starts mid-frame (or carries an encoder's preamble) recovers instead of failing.
+ */
+export declare class AdtsFrameReader {
+    private buffered;
+    /**
+     * Append `chunk` and return every complete frame now available, each a standalone buffer that still
+     * carries its own ADTS header (the device expects the header on the wire).
+     */
+    push(chunk: Buffer): Buffer[];
+    /** Bytes held back awaiting the rest of their frame — non-zero mid-stream, zero on a clean boundary. */
+    get pending(): number;
+}

package/dist/transport/p2p/annexb.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Annex-B elementary-stream helpers — the single NAL-sniffing source of truth for the P2P media
+ * pipeline. Both the live source (codec tag on every frame) and the fMP4 muxer (parameter sets for
+ * the init segment) read the stream through here, so the start-code scan + NAL-type decode lives in
+ * exactly one place.
+ *
+ * H.264 (Annex-B): NAL type = `byte & 0x1f`; SPS = 7, PPS = 8, IDR = 5.
+ * H.265/HEVC (Annex-B): NAL type = `(byte >> 1) & 0x3f`; VPS = 32, SPS = 33, PPS = 34, IDR = 19/20.
+ *
+ * @module p2p/annexb
+ */
+import type { VideoCodec } from "../../core/contracts.js";
+/** Split an Annex-B access unit into its individual NAL bodies (start codes stripped). */
+export declare function splitAnnexbNals(buf: Buffer): Buffer[];
+/**
+ * Sniff the codec of an Annex-B access unit by its parameter-set NAL units. Returns `undefined` when
+ * the buffer carries no config NAL (a plain delta frame) — the caller should carry the last-known
+ * codec rather than guess. Only the first 64 bytes are scanned (config NALs lead the access unit).
+ */
+export declare function sniffAnnexbCodec(buf: Buffer): VideoCodec | undefined;
+/** Parameter sets extracted from a keyframe access unit — the input to an fMP4 init segment. */
+export interface ParamSets {
+    codec: VideoCodec;
+    /** H.264 SPS / H.265 SPS NAL bodies (start-code stripped), in stream order. */
+    sps: Buffer[];
+    /** H.264 PPS / H.265 PPS NAL bodies. */
+    pps: Buffer[];
+    /** H.265 VPS NAL bodies (empty for H.264). */
+    vps: Buffer[];
+}
+/**
+ * Extract the SPS/PPS (and, for H.265, VPS) parameter-set NAL bodies from a keyframe access unit.
+ * Each returned buffer is the raw NAL (start-code stripped), ready to embed in an `avcC` / `hvcC`
+ * decoder-config record. Returns `undefined` if no parameter sets are present.
+ */
+export declare function extractParamSets(buf: Buffer): ParamSets | undefined;
+/**
+ * The parameter sets in force after `buf`, folding what it announces into `current`.
+ *
+ * A camera commonly announces SPS/PPS ONCE, with the first keyframe of a stream, so anything that will
+ * later hand a burst to a decoder has to watch EVERY unit go past — including ones it discards.
+ *
+ * Folds per kind rather than replacing wholesale, because a decoder retains the last set it was given of
+ * EACH kind: a unit announcing an SPS alone re-states that SPS and says nothing about the PPS, so
+ * replacing the whole record would drop a PPS that is still in force. A codec change replaces
+ * everything — sets from another codec describe a different bitstream.
+ *
+ * Cheap on the overwhelmingly common case: {@link extractParamSets} answers from a bounded head scan when
+ * a unit carries no config NAL, so an ordinary delta frame costs no full-buffer walk.
+ */
+export declare function updatedParamSets(buf: Buffer, current: ParamSets | undefined): ParamSets | undefined;
+/**
+ * Re-emit `sets` as Annex-B NALs immediately ahead of `annexb`, so a unit whose parameter sets were
+ * sent earlier in the stream becomes decodable on its own.
+ *
+ * A decoder reads parameter sets in stream order, so they are emitted VPS → SPS → PPS: a PPS ahead of
+ * the SPS it references is as useless as none at all. Sets carrying no NALs return the input unchanged
+ * rather than an equal copy.
+ *
+ * Emitting a duplicate set is harmless — a decoder overwrites the entry with the same id — which is why
+ * this needs no knowledge of what the unit already carries; {@link extractParamSets} answers what a
+ * unit carries already.
+ */
+export declare function prefixParamSets(annexb: Buffer, sets: ParamSets): Buffer;
+/**
+ * Whether an Annex-B access unit contains an IDR (keyframe) NAL. Cheap scan used to key-align the
+ * ring buffer / fragment boundaries when the frame header's keyframe flag isn't authoritative.
+ */
+export declare function hasIdr(buf: Buffer, codec: VideoCodec): boolean;
+/** A width/height pair in luma samples. */
+export interface Size {
+    width: number;
+    height: number;
+}
+/**
+ * What a parameter set says a picture's dimensions are — both of them.
+ *
+ * A stream states TWO sizes and a consumer needs whichever matches what it holds. {@link CodedGeometry.width}
+ * and `height` are the DISPLAY size, the picture as a viewer should see it. {@link CodedGeometry.coded} is the
+ * size it is actually coded at, rounded up to the macroblock (H.264) or CTU (H.265) grid, and
+ * {@link CodedGeometry.crop} is the window between them, already scaled from the chroma units the syntax
+ * states them in into luma samples.
+ *
+ * The distinction is not a refinement: 1080 is not a multiple of 16, so the commonest geometry there is codes
+ * 1088 rows and crops 8 away. A caller that muxes or measures wants the display size; a caller DECODING frames
+ * itself gets the coded size back from its decoder and needs the window to crop with — one that assumes the two
+ * are the same emits eight rows of encoder padding and calls the result 1088 tall.
+ */
+export interface CodedGeometry extends Size {
+    /** The size the picture is coded at — macroblock- or CTU-aligned, and never smaller than the display size. */
+    coded: Size;
+    /** The crop (H.264) or conformance (H.265) window, in LUMA samples. */
+    crop: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+}
+/**
+ * Profiles whose SPS carries the chroma, bit-depth and scaling-matrix fields (H.264 Annex A).
+ *
+ * `144` is the 2005-edition High 4:4:4 that `244` replaced. It is absent from the current standard's list but
+ * present in streams, and a set read without its branch lands mid-element — so it is carried here rather
+ * than left to misparse into a plausible geometry.
+ */
+export declare const H264_CHROMA_PROFILES: Set<number>;
+/**
+ * The picture geometry a decoder will produce from the parameter sets in force, or `undefined` when no
+ * SPS could be read.
+ *
+ * This is the authority on a live stream's geometry. A frame header states the geometry at capture start,
+ * and a source that reconfigures mid-session leaves it contradicting the bytes it is sending — so a
+ * consumer that rebuilt a decoder from the header would size it for a picture the stream is not carrying.
+ * The SPS is what the picture actually is.
+ *
+ * The crop and conformance offsets are part of the answer rather than a refinement of it: 1080 is not a
+ * multiple of the 16-sample macroblock, so a 1080p H.264 stream codes 1088 rows and crops 8 away. A read
+ * that stopped at the coded size would be wrong by exactly that on the commonest geometry there is.
+ *
+ * Answers from the LAST SPS of the set, which is the one in force. AV1 is not parsed — the SDK decodes no
+ * AV1 sequence header, and a size from another codec's syntax would be a fabrication.
+ */
+export declare function codedGeometry(sets: ParamSets): CodedGeometry | undefined;

package/dist/transport/p2p/codec.d.ts

@@ -0,0 +1,166 @@
+export interface Address {
+    host: string;
+    port: number;
+}
+/** Magic word at the start of every P2P data frame. */
+export declare const MAGIC_WORD = "XZYH";
+/** UDP message types (1st byte always 0xf1). */
+export declare const RequestMessageType: {
+    readonly LOCAL_LOOKUP: Buffer<ArrayBuffer>;
+    readonly LOOKUP_WITH_KEY: Buffer<ArrayBuffer>;
+    readonly LOOKUP_WITH_KEY2: Buffer<ArrayBuffer>;
+    readonly CHECK_CAM: Buffer<ArrayBuffer>;
+    readonly CHECK_CAM2: Buffer<ArrayBuffer>;
+    readonly PING: Buffer<ArrayBuffer>;
+    readonly PONG: Buffer<ArrayBuffer>;
+    readonly DATA: Buffer<ArrayBuffer>;
+    readonly ACK: Buffer<ArrayBuffer>;
+    readonly END: Buffer<ArrayBuffer>;
+};
+export declare const ResponseMessageType: {
+    readonly LOCAL_LOOKUP_RESP: Buffer<ArrayBuffer>;
+    readonly LOOKUP_ADDR: Buffer<ArrayBuffer>;
+    readonly LOOKUP_ADDR2: Buffer<ArrayBuffer>;
+    readonly CAM_ID: Buffer<ArrayBuffer>;
+    readonly TURN_SERVER_CAM_ID: Buffer<ArrayBuffer>;
+    readonly PING: Buffer<ArrayBuffer>;
+    readonly PONG: Buffer<ArrayBuffer>;
+    readonly DATA: Buffer<ArrayBuffer>;
+    readonly ACK: Buffer<ArrayBuffer>;
+    readonly END: Buffer<ArrayBuffer>;
+};
+/** P2P data-channel types (2nd byte of the data-type header). */
+export declare const P2PDataType: {
+    readonly DATA: 0;
+    readonly VIDEO: 1;
+    readonly CONTROL: 2;
+    readonly BINARY: 3;
+};
+export declare const P2PDataTypeHeader: {
+    readonly DATA: Buffer<ArrayBuffer>;
+    readonly VIDEO: Buffer<ArrayBuffer>;
+    readonly CONTROL: Buffer<ArrayBuffer>;
+    readonly BINARY: Buffer<ArrayBuffer>;
+};
+/** The fixed-width 16-byte header of every P2P data frame (after "XZYH"). */
+export declare const P2P_DATA_HEADER_BYTES = 16;
+export interface P2PDataFrameHeader {
+    commandId: number;
+    bytesToRead: number;
+    channel: number;
+    signCode: number;
+    type: number;
+}
+/** Frame a UDP packet: `[msgType:2][payloadLen:2 BE][payload]`. */
+export declare function frameMessage(msgType: Buffer, payload?: Buffer): Buffer;
+/** True if `msg` begins with the given 2-byte message type. */
+export declare function hasHeader(msg: Buffer, type: Buffer): boolean;
+/** Pad a string into a fixed-width (multiple-of-chunk) zero-filled buffer. */
+export declare function stringWithLength(input: string, chunkLength?: number): Buffer;
+/** `EUPRCAM-000000-XXXXX` → the 20-byte buffer used in lookup/check payloads. */
+export declare function p2pDidToBuffer(p2pDid: string): Buffer;
+/**
+ * Decode a station's `p2p_conn` / `app_conn` string into the eufy cloud lookup
+ * server addresses (port 32100). XOR cipher with a fixed lookup table, seed 0x39.
+ */
+export declare function decodeP2PCloudIPs(data: string): Address[];
+/**
+ * The "Level 1" AES-128-ECB key for P2P command/control encryption — derivable
+ * from sn + p2p_did alone (no cipher needed). HomeBase control-channel
+ * notifications (sensor/alarm events) use exactly this key.
+ */
+export declare function p2pCommandEncryptionKey(stationSn: string, p2pDid: string): string;
+/** AES-128-ECB decrypt of a P2P payload (no padding). */
+export declare function decryptP2PData(data: Buffer, key: Buffer): Buffer;
+/** The `cipher_id` named in a decrypted `CMD_GATEWAYINFO` (1100) payload (uint16 LE @0). */
+export declare function gatewayInfoCipherId(gwPayload: Buffer): number;
+/** Options for {@link eciesUnwrap}. */
+export interface EciesUnwrapOptions {
+    /**
+     * When true, the envelope carries a trailing 32-byte HMAC tag over `iv ‖ ct` (the video
+     * `CMD_VIDEO_FRAME` envelope, which is `ephPub(33) ‖ iv(16) ‖ ct(48) ‖ HMAC(32)`). The tag is
+     * verified with `kdf[16:48]` as the MAC key and a mismatch yields `undefined`. When false (the
+     * `CMD_GATEWAYINFO` envelope, `ephPub(33) ‖ iv(16) ‖ ct(48)`) there is no HMAC step.
+     */
+    verifyHmac?: boolean;
+    /** Whether the AES-128-CBC plaintext is PKCS7-padded (video: true). Default false (zero-/no-pad). */
+    pkcs7?: boolean;
+}
+/**
+ * The shared ECIES unwrap primitive used by both the gateway and the video paths.
+ *
+ * `envelope` = `ephemeralPub(33, compressed P-256) ‖ iv(16) ‖ ct(48) [‖ HMAC(32)]`. Derivation:
+ * `S = ECDH_X(eccPriv, ephPub)` → `kdf = eufyKDF(S)` → `aesKey = kdf[0:16]`; (optionally verify
+ * `HMAC(kdf[16:48], iv‖ct) == tag`) → `AES-128-CBC(aesKey, iv, ct)` → plaintext. Returns the
+ * decrypted bytes, or `undefined` on any parse / HMAC / cipher failure (fails closed, never throws).
+ */
+export declare function eciesUnwrap(envelope: Buffer, eccPrivateKeyHex: string, options?: EciesUnwrapOptions): Buffer | undefined;
+/**
+ * Derive the P2P **level-2** (signCode 2/8) AES-256-GCM session key from a *decrypted*
+ * `CMD_GATEWAYINFO` (1100) payload and the station's ECC private key (from `get_ciphers`).
+ *
+ * Layout of the decrypted payload: `cipher_id(2 LE) ‖ 0000 ‖ ECIES-envelope(129)`, where the
+ * envelope is `ephemeralPub(33, compressed P-256) ‖ iv(16) ‖ ciphertext(48)`. ECIES =
+ * ECDH(eccPriv, ephemeralPub) → eufyKDF(SHA-256/HMAC, label "ECIES") → AES-128-CBC decrypt →
+ * 32-byte session key. Reversed from `libmega_media_sdk.so`; verified to reproduce the live key.
+ * Returns the 32-byte key, or undefined if the inputs don't parse.
+ */
+export declare function deriveLevel2KeyFromGatewayInfo(gwPayload: Buffer, eccPrivateKeyHex: string): Buffer | undefined;
+/** Local-lookup payload: two zero bytes. */
+export declare function buildLocalLookupPayload(): Buffer;
+/** Cloud-lookup payload (variant 2): `[p2pDid:20][dskKey][0x00000000]`. */
+export declare function buildLookupWithKeyPayload2(p2pDid: string, dskKey: string): Buffer;
+/**
+ * Cloud-lookup payload — the CLASSIC variant (`LOOKUP_WITH_KEY`, 0xf126), reverse-engineered
+ * byte-exact against the app's own request (cold-start, phone
+ * force-stopped then reopened). Distinct from {@link buildLookupWithKeyPayload2} (`LOOKUP_WITH_KEY2`,
+ * 0xf16a) which eufy-sdk already sent: that variant only ever got relay-pool candidates back for a
+ * remote (cross-WAN) target; THIS variant is what got the real app a genuine direct-device address.
+ *
+ * `[p2pDid:20][selfAddr:16][clientVersion:4 = 02 05 01 05][dskKey][0x00000000]`. `selfAddr` is the
+ * caller's own observed LAN host:port (the socket's own bound address) — a STUN-like self-report, NOT
+ * the target's address. `clientVersion` was `02 05 01 05` in every capture; reproduced verbatim since
+ * its exact semantics (and whether it's validated) are unconfirmed.
+ */
+export declare function buildLookupWithKeyPayload(p2pDid: string, selfHost: string, selfPort: number, dskKey: string): Buffer;
+/** CHECK_CAM hole-punch payload: `[p2pDid:20][0x000000]`. */
+export declare function buildCheckCamPayload(p2pDid: string): Buffer;
+/** 10-byte command header: `[dataTypeHeader:2][seq:2 BE]["XZYH"][cmd:2 LE]`. */
+export declare function buildCommandHeader(seqNumber: number, commandType: number, dataTypeHeader?: Buffer): Buffer;
+/** 10-byte empty command body for the given channel (used by CMD_GATEWAYINFO etc.). */
+export declare function buildVoidCommandPayload(channel?: number): Buffer;
+/** AES-128-ECB encrypt (no auto-padding) — P2P control payloads. Inverse of decryptP2PData. */
+export declare function encryptP2PData(data: Buffer, key: Buffer): Buffer;
+/** Zero-pad to a multiple of `blocksize` (eufy P2P pads with 0x00, NOT PKCS7). */
+export declare function paddingP2PData(data: Buffer, blocksize?: number): Buffer;
+/**
+ * Command body carrying a string `value` (e.g. CMD_SET_PAYLOAD JSON). Mirrors the
+ * app's `buildCommandWithStringTypePayload`: `[len:2 LE][00 00][01 00][channel,encType][00 00][data]`.
+ * When `key` is given the data is zero-padded to 16 and AES-128-ECB encrypted, and
+ * `encType` is written in the channel word (level-1 encryption = 1).
+ */
+export declare function buildStringCommandPayload(value: string, channel?: number, key?: Buffer, encType?: number): Buffer;
+/**
+ * Build an **int+string** command body: `valueSub(u32 LE) ‖ value(u32 LE) ‖ strValue(len-prefixed)`,
+ * AES-128-ECB encrypted (level-1) like {@link buildStringCommandPayload}. This is the wire shape the
+ * eufy app uses for the floodlight/spotlight manual switch (`CMD_SET_FLOODLIGHT_MANUAL_SWITCH` 1400)
+ * on IndoorOutdoor / SoloCam-spotlight / Cam2C/3 families — where `value` = 0/1, `valueSub` = the
+ * device channel, and `strValue` = the admin `account_id`. The `strValue` uses the 128-byte-chunk
+ * length prefix ({@link stringWithLength}).
+ */
+export declare function buildIntStringCommandPayload(value: number, valueSub: number, strValue: string, channel?: number, key?: Buffer, encType?: number): Buffer;
+/**
+ * Build a command body around an ALREADY-encrypted (or plaintext) `data` buffer with an explicit
+ * `signCode` — used for level-2 (`signCode 8`, AES-256-GCM) commands like the media-start 1350 the
+ * app sends. Same on-wire layout as `buildStringCommandPayload` but the caller supplies the body and
+ * the signCode verbatim (no ECB step): `len(u16) ‖ 0000 ‖ 0100 ‖ [channel, signCode] ‖ 0000 ‖ data`.
+ */
+export declare function buildRawCommandPayload(data: Buffer, channel?: number, signCode?: number, magic?: [number, number], streamId?: number): Buffer;
+/** ACK payload for a received DATA frame: `[dataTypeHeader:2][count:2 BE][seqNo:2 BE]`. */
+export declare function buildAckPayload(dataTypeHeader: Buffer, seqNo: number): Buffer;
+/** Parse the 16-byte data-frame header that follows the "XZYH" magic. */
+export declare function parseDataFrameHeader(frame: Buffer): P2PDataFrameHeader;
+/** Parse a LOOKUP_ADDR / LOOKUP_ADDR2 response into a device address. */
+export declare function parseLookupAddr(msg: Buffer): Address;
+/** Read a NUL-terminated UTF-8 string (CMD_NOTIFY_PAYLOAD carries JSON this way). */
+export declare function readNullTerminatedString(data: Buffer, encoding?: BufferEncoding): string;