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

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

@@ -0,0 +1,187 @@
+/**
+ * Managed talkback session over P2P — the send-side twin of `live-stream.ts`. Takes AAC-LC audio from
+ * a host, recovers frame boundaries, and paces the frames onto the wire at their own playback rate,
+ * bracketed by the device's start/stop control frames.
+ *
+ * Pacing is the reason this exists rather than a bare `sendAudioFrame` loop. Each AAC-LC frame at
+ * 16 kHz is 1024 samples — exactly 64 ms of audio — and the device plays what arrives when it arrives.
+ * A host piping a file would otherwise deliver a minute of audio in a few hundred milliseconds and
+ * lose all but the tail. A live source paces itself and simply keeps the queue near-empty.
+ *
+ * The pacer is **wall-clock**, not tick-counted: a timer callback that runs late releases every frame
+ * it owes rather than one. Releasing one per tick loses each late tick permanently, which measures as a
+ * feed slower than realtime on a loaded event loop — and this feature attaches to a shared live source,
+ * so muxing video on the same loop is the normal case, not the edge case.
+ *
+ * @module p2p/talkback
+ */
+import { EventEmitter } from "node:events";
+import { Writable } from "node:stream";
+import type { AacEncoder, StreamBudgetNotice, TalkbackHandle } from "../../core/contracts.js";
+import { type Logger } from "../../core/logger.js";
+/**
+ * The subset of the session this needs — start/stop the path, push one frame, and report a frame the
+ * device never acknowledged. The audio channel is ordered, so an abandoned frame is a permanent hole
+ * that stalls everything behind it; the listener pair lets that surface instead of going silent.
+ */
+export interface TalkbackSink {
+    startTalkback(channel: number, homeBaseAttached: boolean): boolean;
+    stopTalkback(channel: number, homeBaseAttached: boolean): boolean;
+    sendAudioFrame(channel: number, frame: Buffer): void;
+    on?(event: "audioGap", listener: (seq: number) => void): unknown;
+    off?(event: "audioGap", listener: (seq: number) => void): unknown;
+}
+export interface TalkbackOptions {
+    channel: number;
+    homeBaseAttached: boolean;
+    /** Converts PCM to ADTS when the caller feeds PCM instead of AAC. */
+    encoder?: AacEncoder;
+    /**
+     * Releases the media session this talkback is riding inside. Called once on {@link Talkback.stop}.
+     * The device only plays host audio while its media session is open (verified live: the identical
+     * frames are silent without one), so the session is held for the talkback's whole lifetime.
+     */
+    releaseMedia?(): void;
+    /**
+     * Frames the pacing queue holds before `writable()` applies backpressure. The default is two
+     * seconds of audio — enough to ride out scheduler jitter without letting a file source buffer the
+     * whole clip in memory.
+     */
+    highWaterFrames?: number;
+    /**
+     * Stop by itself after this long with nothing written. A handle holds a consumer on the shared live
+     * source and a repeating timer, and neither is reaped by anything but an explicit
+     * {@link Talkback.stop} — a battery camera's power budget does not apply to a wired one. A caller
+     * that drops the handle would otherwise pin a P2P pull for the life of the process. Pass `0` to
+     * disable. Default {@link DEFAULT_IDLE_TIMEOUT_MS}.
+     */
+    idleTimeoutMs?: number;
+    logger?: Logger;
+}
+/**
+ * How long a talkback waits for audio before stopping itself. Comfortably longer than any gap a live
+ * or press-to-talk source produces mid-sentence, and short enough that an abandoned handle does not
+ * outlive the conversation it belonged to.
+ */
+export declare const DEFAULT_IDLE_TIMEOUT_MS = 30000;
+/**
+ * A talkback session bound to one camera channel. Opens the device's path on construction via
+ * {@link start}, then drains queued frames on a fixed 64 ms tick until {@link stop}.
+ */
+export declare class Talkback extends EventEmitter implements TalkbackHandle {
+    private readonly sink;
+    private readonly opts;
+    private readonly reader;
+    private readonly queue;
+    private readonly logger;
+    private readonly highWater;
+    private readonly idleTimeoutMs;
+    private timer?;
+    private started;
+    private stopped;
+    private ended;
+    private announcedFinish;
+    private onRoom?;
+    /** When the next frame is due, in `Date.now()` terms — the pacer's wall-clock cursor. */
+    private nextDueAt;
+    private lastWriteAt;
+    /**
+     * Serializes the encoder path. `write()` must not block a synchronous caller, so an encode runs
+     * detached — but two detached encodes can settle out of order, and both push into a STATEFUL
+     * {@link AdtsFrameReader}. Chaining keeps the frames in the order they were written and keeps the
+     * end-of-input flush behind the last pending encode.
+     */
+    private chain;
+    private readonly onAudioGap;
+    constructor(sink: TalkbackSink, opts: TalkbackOptions);
+    /** Frames still queued for the wire. */
+    get pending(): number;
+    /**
+     * Open the device's talkback path and begin the pacing tick. Throws when the topology's control
+     * frame could not be sent — for a HomeBase-attached camera that means the level-2 key was never
+     * negotiated, which would otherwise leave a silent session that accepts audio nobody hears.
+     */
+    start(): this;
+    /**
+     * Queue audio. Bytes are ADTS AAC, or PCM when an encoder was supplied; either way the input is
+     * treated as a stream, so a chunk carrying part of a frame is held until the rest arrives.
+     *
+     * Audio written after {@link end} is dropped with an `error` rather than queued: `finished` has
+     * either already fired or is owed on the frames written before it, so a late chunk would either play
+     * after the clip was declared complete or never be announced at all.
+     */
+    write(chunk: Buffer): void;
+    /**
+     * Declare the input finished. Nothing more may be written; once the queue drains, `finished` fires.
+     * `writable()` calls this from its `final`, so a piped source needs no explicit call.
+     */
+    end(): void;
+    /**
+     * Run PCM through the caller's encoder. Kept off {@link write}'s return path so a synchronous
+     * caller isn't forced to await; an encoder failure surfaces as an `error` event.
+     */
+    private encodeAndEnqueue;
+    /**
+     * Admit whole frames to the pacing queue, rejecting any whose parameters the device cannot play or
+     * whose length it refuses. A rejected frame is dropped with an `error` rather than silently
+     * swallowed: passing it through would produce audible garbage.
+     */
+    private enqueue;
+    /**
+     * Release every frame the wall clock says is due, then report the clip finished once the input has
+     * ended and nothing is left. Pacing is unconditional: it tracks the audio's own playback rate and
+     * never waits on the device's acknowledgements, because the device is playing a continuous stream
+     * and a slowed feed starves it.
+     *
+     * The cursor advances by one frame's duration per frame sent rather than being reset to `now`, so a
+     * timer that fires late sends what it owes and the feed stays at realtime. When the queue runs dry
+     * the cursor is re-based one frame ahead of `now`: the silence was the source's, and owing frames for
+     * it would burst them the moment audio resumes.
+     */
+    private tick;
+    /**
+     * Stop a talkback nothing is feeding any more. Only armed while the queue is empty — a source that
+     * is merely slow keeps frames in flight, and a live source pushes on its own cadence. It covers a
+     * finished clip too: a caller that listens for `finished` but never stops still holds the shared
+     * consumer, which is the same leak as dropping the handle outright.
+     */
+    private idleCheck;
+    /** Emit `finished` once, when the input has ended and every queued frame has reached the wire. */
+    private announceFinishIfDone;
+    /** Hand a withheld `writable()` callback back, so the source resumes. */
+    private releaseWriter;
+    /**
+     * Report a failure without being able to kill the host. `error` on an `EventEmitter` THROWS when
+     * nothing is listening, and every call site here is either inside the pacing interval or on a
+     * detached encode — where that throw aborts the process rather than reaching a caller. The common
+     * case is audio that simply isn't 16 kHz mono, which must not take the process down.
+     */
+    private fail;
+    /**
+     * A Writable over {@link write} that withholds its callback while the queue is at the high-water
+     * mark — which is what turns `pipe()` from a file into playback at speed rather than a memory spike.
+     */
+    writable(): Writable;
+    /** Drain an encoder's partial trailing block, so the last syllable is not lost. */
+    private flushEncoder;
+    /**
+     * Close the path: stop pacing, drop anything still queued, and send the stop control frame. Queued
+     * audio is deliberately discarded — `finished` is the event that says everything queued has already
+     * reached the wire.
+     *
+     * Everything after the guard runs under `try`/`finally` because the teardown calls back into
+     * caller-supplied code (the encoder's `close`, a withheld stream callback, the session's stop frame),
+     * any of which can throw. `releaseMedia` must run regardless: the idempotence guard has already
+     * latched by then, so a skipped release can never be retried, and the shared consumer would stay
+     * attached — holding the P2P pull open until the process exits.
+     */
+    stop(): Promise<void>;
+}
+export interface Talkback {
+    on(event: "finished" | "stop", listener: () => void): this;
+    on(event: "error", listener: (err: Error) => void): this;
+    on(event: "budget", listener: (notice: StreamBudgetNotice) => void): this;
+    emit(event: "finished" | "stop"): boolean;
+    emit(event: "error", err: Error): boolean;
+    emit(event: "budget", notice: StreamBudgetNotice): boolean;
+}

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

@@ -0,0 +1,150 @@
+/** Parsed fields of a `CMD_VIDEO_FRAME` 22-byte header. */
+export interface VideoFrameHeader {
+    /**
+     * Length of the body THIS frame carries, from u32 LE @ 0x00 — not the length of the access unit it
+     * belongs to.
+     *
+     * A station serves a unit larger than {@link STATION_CHUNK_BYTES} as several frames, and each one
+     * declares only its own share: measured on two models, a 70190-byte unit arrived as `64000` then
+     * `6190`, and a 104451-byte keyframe as `64000` then `40451`. A frame that carries a whole unit
+     * declares the whole unit, however large — a captured keyframe declares 0x3b323.
+     */
+    payloadLength: number;
+    /** True when flag@0x04 bit0 is set: a keyframe carrying the ECIES envelope. */
+    keyframe: boolean;
+    /** Raw flag byte at 0x04. */
+    flags: number;
+    /**
+     * u16 LE @ 0x06 — repeated across every frame of ONE access unit, which is what makes it usable as
+     * part of a unit's identity. What it counts differs by model (one increments it per unit, another
+     * leaves it 0 for the whole stream), so it is never read as a count on its own.
+     */
+    sequence: number;
+    /** Frame width (s16 LE @ 0x0a). */
+    width: number;
+    /** Frame height (s16 LE @ 0x0c). */
+    height: number;
+    /** Timestamp word (u32 LE @ 0x0e). */
+    timestamp: number;
+}
+/** A successfully decoded video frame. */
+export interface DecodedVideoFrame {
+    /** True if this was a keyframe (IDR) — its envelope re-keyed the decoder. */
+    keyframe: boolean;
+    /** Decrypted H.264 elementary-stream bytes. */
+    h264: Buffer;
+    /** Frame width in pixels. */
+    width: number;
+    /** Frame height in pixels. */
+    height: number;
+}
+/**
+ * Parse the 22-byte `CMD_VIDEO_FRAME` header. Does not validate lengths beyond the header itself,
+ * so it is safe to call on a (sufficiently long) buffer to inspect frame metadata without keys.
+ */
+export declare function parseVideoFrameHeader(payload: Buffer): VideoFrameHeader | undefined;
+/**
+ * Decodes a single P2P video stream into H.264. Construct one per stream with the camera's 32-byte
+ * ECC private key; feed it `CMD_VIDEO_FRAME` payloads in order. Keyframes re-key the decoder via
+ * their ECIES envelope; P/B-frames reuse the cached media key. All failure modes (short/garbage
+ * frame, wrong key, tampered HMAC, GCM auth failure) return `undefined` — the decoder never throws.
+ */
+export declare class VideoFrameDecoder {
+    private readonly eccPrivateKeyHex;
+    private mediaKey?;
+    /** @param eccPrivateKey the camera's 32-byte ECC private key (P-256 scalar). */
+    constructor(eccPrivateKey: Buffer);
+    /** The media key recovered from the most recent keyframe, if any. */
+    get currentMediaKey(): Buffer | undefined;
+    /**
+     * Recover the per-stream media key from a keyframe's 129-byte ECIES envelope: ECIES unwrap
+     * (ECDH → eufyKDF → AES-128-CBC, with the trailing HMAC verified) → 32-byte AES-256-GCM key.
+     */
+    private unwrapMediaKey;
+    /**
+     * Decode one video frame. Returns the keyframe flag and decrypted H.264 bytes, or `undefined`
+     * if the frame is malformed, the envelope/key is wrong, or GCM authentication fails.
+     */
+    decodeFrame(payload: Buffer): DecodedVideoFrame | undefined;
+}
+/** One whole access unit recovered from the frame (or frames) the station sent it in. */
+export interface AssembledAccessUnit {
+    /** True when the unit's own header flagged it a keyframe — a point a consumer may begin decoding at. */
+    keyframe: boolean;
+    /** Frame width the unit's header declared. */
+    width: number;
+    /** Frame height the unit's header declared. */
+    height: number;
+    /** The complete payload, as long as the header said it would be. */
+    data: Buffer;
+}
+/**
+ * The payload size a station fills a `CMD_VIDEO_FRAME` to before splitting an access unit across
+ * several of them.
+ *
+ * Verified on two independent camera models on one account: every frame of a split unit declared
+ * EXACTLY this, and the unit's last frame declared less.
+ *
+ * Matched by equality, never as a floor. Stations that do not split deliver whole units in one frame far
+ * above this — measured at 148057, 231954 and 234670 bytes on three other models — and treating "at least
+ * this big" as "more is coming" holds those units back and then discards them as truncated, which costs
+ * exactly the keyframes a decoder cannot start without.
+ */
+export declare const STATION_CHUNK_BYTES = 64000;
+/**
+ * Reassembles a `CMD_VIDEO_FRAME` access unit the station split across several frames.
+ *
+ * Each frame declares only the payload IT carries ({@link VideoFrameHeader.payloadLength}), so the unit's
+ * total length is nowhere on the wire and cannot be waited for. What the wire does carry, verified on two
+ * models:
+ *
+ *  - the frames of one unit **repeat its header** — same timestamp, same {@link VideoFrameHeader.sequence} —
+ *    while consecutive units differ in both;
+ *  - every frame of a split unit is filled to {@link STATION_CHUNK_BYTES} except the last;
+ *  - a frame that STARTS a unit begins with an Annex-B start code once decoded, and a continuation begins
+ *    mid-NAL, so it does not.
+ *
+ * A unit is therefore held only while its latest frame is full, and completed the moment a shorter one
+ * arrives — no delivery latency for the overwhelming majority of units, which arrive in one frame below
+ * the threshold. The identity match and the missing start code are required TOGETHER before appending:
+ * either alone would let two decodable units merge, and a merge is invisible to a consumer that trusts
+ * the contract.
+ *
+ * **A unit is delivered only when it is complete.** A lost datagram makes the P2P layer discard the frame
+ * it was reassembling, so a unit whose tail never arrives is ended by the next unit's first frame while
+ * still full — that one is dropped and reported, never handed on short. Truncated bytes are worse than
+ * none: a decoder given an access unit shorter than its own slice headers promise reports bitstream
+ * truncation and produces no picture at all.
+ *
+ * Two consequences worth stating. A unit that is exactly the threshold long, or an exact multiple of it,
+ * ends on a full frame and is dropped as truncated — one frame in ~64000, reported, and the alternative is
+ * handing a decoder bytes that may genuinely be short. And a station that fills to some OTHER size is not
+ * recognised: its units stay exactly as they arrive rather than being mis-joined.
+ */
+export declare class AccessUnitAssembler {
+    private readonly onDropped?;
+    private open?;
+    private droppedUnits;
+    /**
+     * @param onDropped called for each incomplete unit discarded, with what had arrived, how many frames it
+     * arrived in, and how many this assembler has dropped in total — a running count, so no caller keeps
+     * its own.
+     */
+    constructor(onDropped?: ((drop: {
+        carried: number;
+        chunks: number;
+        count: number;
+    }) => void) | undefined);
+    /**
+     * Feed one raw `CMD_VIDEO_FRAME` payload; returns the access units it completed — none while a unit is
+     * still being filled, one in the ordinary case.
+     *
+     * `decode` extracts the payload of a frame, whatever the stream's encryption: it is called for EVERY
+     * frame, including a continuation, because a continuation carries its own wrapped key ahead of its share
+     * of the payload (measured: 129 bytes beyond what its header declares, exactly as a unit's first frame
+     * carries).
+     */
+    push(payload: Buffer, decode: (payload: Buffer) => Buffer | undefined): AssembledAccessUnit[];
+    /** Forget an incomplete unit, counting and reporting it. */
+    private discard;
+}

package/dist/transport/p2p/write-commands.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Direct-binary write helpers.
+ *
+ * The capability-driven command recipes live in the capability modules
+ * (`src/model/capabilities/*`): each module owns its own `buildCommand`, and the barrel's
+ * `buildCommand()` resolves across them. This file keeps ONLY the **direct-binary** body builder
+ * — a packed struct, not a JSON recipe — used by `EufyMega.sendDirectBinary` for camera on/off +
+ * spotlight brightness/color-temp/enable. No dependency on the capability barrel (avoids a cycle).
+ */
+/**
+ * Build a level-2 direct-binary control body: `[u32 channel?][u32 value][account_id ASCII pad→128]`.
+ * Omit `channel` for the channel-less station form (e.g. HomeBase alarm volume). See the struct note above.
+ */
+export declare function buildDirectBinaryBody(value: number, accountId: string, channel?: number): Buffer;
+/**
+ * Body for the device/hub rename command (`SET_DEVICE_NAME` 1217 / `SET_HUB_NAME` 1216). A 261-byte
+ * struct confirmed against the app: `[u32 = 0][u8 device_channel][name → 128B, null-padded]
+ * [account_id → 128B, null-padded]`. Sent signCode 8 on the station channel (255). The name is UTF-8
+ * (matching the app), truncated to fit 127 bytes so the field stays null-terminated.
+ */
+export declare function buildDeviceNameBody(channel: number, name: string, accountId: string): Buffer;

package/dist/transport/protobuf.d.ts

@@ -0,0 +1,5 @@
+/** The `protobufjs` module shape, loaded on demand. */
+type Protobuf = typeof import("protobufjs");
+/** The engine, loading it on the first call. The ONLY runtime reference to `protobufjs` here. */
+export declare function protobufjs(): Protobuf;
+export {};

package/dist/transport/push/fcm.d.ts

@@ -0,0 +1,23 @@
+import type { FcmCredentials } from "./types.js";
+import { type Logger } from "../../core/logger.js";
+export declare const FCM: {
+    readonly PROJECT_ID: "batterycam-3250a";
+    readonly API_KEY: "AIzaSyCSz1uxGrHXsEktm7O3_wv-uLGpC9BvXR8";
+    readonly APP_ID: "1:348804314802:android:440a6773b3620da7";
+    readonly SENDER_ID: "348804314802";
+    readonly PACKAGE: "com.oceanwing.battery.cam";
+    readonly CERT_SHA1: "F051262F9F99B638F3C76DE349830638555B4A0A";
+    readonly AUTH_VERSION: "FIS_v2";
+    readonly SDK_VERSION: "a:16.3.1";
+};
+/** Generate a valid Firebase Installation ID (22 url-safe chars, starts c-f). */
+export declare function generateFid(): string;
+export declare class FcmRegistrar {
+    private readonly logger;
+    constructor(logger?: Logger);
+    /** Full registration → FcmCredentials. */
+    register(): Promise<FcmCredentials>;
+    private installFid;
+    private checkin;
+    private gcmRegister;
+}

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

@@ -0,0 +1,6 @@
+export { PushClient } from "./push-client.js";
+export { FcmRegistrar, generateFid, FCM } from "./fcm.js";
+export { McsParser } from "./parser.js";
+export { FileFcmStore, MemoryFcmStore, type FcmStore, type PersistedPush } from "./store.js";
+export { MessageTag } from "./message-tags.js";
+export type { PushEvent, ThumbnailCandidate, ThumbnailCandidateAttribution, PushPayload, PushEnrichment, RawPushMessage, EufyPushMessage, FcmCredentials, McsMessage, } from "./types.js";

package/dist/transport/push/message-tags.d.ts

@@ -0,0 +1,26 @@
+/**
+ * MCS wire-framing tags — the 1-byte tag preceding each framed message on Google's MCS/FCM socket.
+ *
+ * Pure transport framing (login/heartbeat/data-stanza routing); it is NOT a push *event* semantic,
+ * so it lives with the push transport, not in the model's push-event vocabulary
+ * (the model layer's push-event module). The parser and client are its only consumers.
+ */
+export declare enum MessageTag {
+    HeartbeatPing = 0,
+    HeartbeatAck = 1,
+    LoginRequest = 2,
+    LoginResponse = 3,
+    Close = 4,
+    MessageStanza = 5,
+    PresenceStanza = 6,
+    IqStanza = 7,
+    DataMessageStanza = 8,
+    BatchPresenceStanza = 9,
+    StreamErrorStanza = 10,
+    HttpRequest = 11,
+    HttpResponse = 12,
+    BindAccountRequest = 13,
+    BindAccountResponse = 14,
+    TalkMetadata = 15,
+    NumProtoTypes = 16
+}

package/dist/transport/push/parser.d.ts

@@ -0,0 +1,27 @@
+/**
+ * MCS wire-stream parser. The TLS stream is framed as:
+ *   first packet:  [version:1][tag:1][varint length][protobuf]
+ *   then each msg: [tag:1][varint length][protobuf]
+ * Chunks arrive arbitrarily split, so we accumulate and re-enter as data lands.
+ * Implements Google's MCS (mtalk) stream framing.
+ */
+import { EventEmitter } from "node:events";
+export declare class McsParser extends EventEmitter {
+    private data;
+    private state;
+    private messageTag;
+    private messageSize;
+    private sizePacketSoFar;
+    /** Reset for a fresh connection. */
+    reset(): void;
+    /** Feed a chunk of TLS bytes. */
+    handleData(chunk: Buffer): void;
+    private minBytesNeeded;
+    private waitForData;
+    private onVersion;
+    private onTag;
+    private onSize;
+    private onBytes;
+    private next;
+    private emitMessage;
+}

package/dist/transport/push/proto.d.ts

@@ -0,0 +1,11 @@
+import type { Root } from "protobufjs";
+/**
+ * Google MCS + Android check-in protobuf schemas, embedded as strings so they
+ * ship in the build without a file-copy step (protobufjs `parse()` instead of
+ * `load()`). These are Google's public protocol definitions (Chromium MCS /
+ * GServices check-in), not eufy code.
+ */
+export declare const MCS_PROTO = "\nsyntax = \"proto2\";\noption optimize_for = LITE_RUNTIME;\npackage mcs_proto;\n\nmessage HeartbeatPing {\n  optional int32 stream_id = 1;\n  optional int32 last_stream_id_received = 2;\n  optional int64 status = 3;\n}\nmessage HeartbeatAck {\n  optional int32 stream_id = 1;\n  optional int32 last_stream_id_received = 2;\n  optional int64 status = 3;\n}\nmessage ErrorInfo {\n  required int32 code = 1;\n  optional string message = 2;\n  optional string type = 3;\n  optional Extension extension = 4;\n}\nmessage Setting {\n  required string name = 1;\n  required string value = 2;\n}\nmessage HeartbeatStat {\n  required string ip = 1;\n  required bool timeout = 2;\n  required int32 interval_ms = 3;\n}\nmessage HeartbeatConfig {\n  optional bool upload_stat = 1;\n  optional string ip = 2;\n  optional int32 interval_ms = 3;\n}\nmessage ClientEvent {\n  enum Type { UNKNOWN = 0; DISCARDED_EVENTS = 1; FAILED_CONNECTION = 2; SUCCESSFUL_CONNECTION = 3; }\n  optional Type type = 1;\n  optional uint32 number_discarded_events = 100;\n  optional int32 network_type = 200;\n  reserved 201;\n  optional uint64 time_connection_started_ms = 202;\n  optional uint64 time_connection_ended_ms = 203;\n  optional int32 error_code = 204;\n  optional uint64 time_connection_established_ms = 300;\n}\nmessage LoginRequest {\n  enum AuthService { ANDROID_ID = 2; }\n  required string id = 1;\n  required string domain = 2;\n  required string user = 3;\n  required string resource = 4;\n  required string auth_token = 5;\n  optional string device_id = 6;\n  optional int64 last_rmq_id = 7;\n  repeated Setting setting = 8;\n  repeated string received_persistent_id = 10;\n  optional bool adaptive_heartbeat = 12;\n  optional HeartbeatStat heartbeat_stat = 13;\n  optional bool use_rmq2 = 14;\n  optional int64 account_id = 15;\n  optional AuthService auth_service = 16;\n  optional int32 network_type = 17;\n  optional int64 status = 18;\n  reserved 19, 20, 21;\n  repeated ClientEvent client_event = 22;\n}\nmessage LoginResponse {\n  required string id = 1;\n  optional string jid = 2;\n  optional ErrorInfo error = 3;\n  repeated Setting setting = 4;\n  optional int32 stream_id = 5;\n  optional int32 last_stream_id_received = 6;\n  optional HeartbeatConfig heartbeat_config = 7;\n  optional int64 server_timestamp = 8;\n}\nmessage StreamErrorStanza {\n  required string type = 1;\n  optional string text = 2;\n}\nmessage Close {}\nmessage Extension {\n  required int32 id = 1;\n  required bytes data = 2;\n}\nmessage IqStanza {\n  enum IqType { GET = 0; SET = 1; RESULT = 2; IQ_ERROR = 3; }\n  optional int64 rmq_id = 1;\n  required IqType type = 2;\n  required string id = 3;\n  optional string from = 4;\n  optional string to = 5;\n  optional ErrorInfo error = 6;\n  optional Extension extension = 7;\n  optional string persistent_id = 8;\n  optional int32 stream_id = 9;\n  optional int32 last_stream_id_received = 10;\n  optional int64 account_id = 11;\n  optional int64 status = 12;\n}\nmessage AppData {\n  required string key = 1;\n  required string value = 2;\n}\nmessage DataMessageStanza {\n  optional string id = 2;\n  required string from = 3;\n  optional string to = 4;\n  required string category = 5;\n  optional string token = 6;\n  repeated AppData app_data = 7;\n  optional bool from_trusted_server = 8;\n  optional string persistent_id = 9;\n  optional int32 stream_id = 10;\n  optional int32 last_stream_id_received = 11;\n  optional string reg_id = 13;\n  optional int64 device_user_id = 16;\n  optional int32 ttl = 17;\n  optional int64 sent = 18;\n  optional int32 queued = 19;\n  optional int64 status = 20;\n  optional bytes raw_data = 21;\n  optional bool immediate_ack = 24;\n}\nmessage StreamAck {}\nmessage SelectiveAck { repeated string id = 1; }\n";
+export declare const CHECKIN_PROTO = "\nsyntax = \"proto2\";\noption optimize_for = LITE_RUNTIME;\n\nmessage CheckinRequest {\n  optional string imei = 1;\n  optional int64 androidId = 2;\n  optional string digest = 3;\n  required Checkin checkin = 4;\n  message Checkin {\n    required Build build = 1;\n    message Build {\n      optional string fingerprint = 1;\n      optional string hardware = 2;\n      optional string brand = 3;\n      optional string radio = 4;\n      optional string bootloader = 5;\n      optional string clientId = 6;\n      optional int64 time = 7;\n      optional int32 packageVersionCode = 8;\n      optional string device = 9;\n      optional int32 sdkVersion = 10;\n      optional string model = 11;\n      optional string manufacturer = 12;\n      optional string product = 13;\n      optional bool otaInstalled = 14;\n    }\n    optional int64 lastCheckinMs = 2;\n    repeated Event event = 3;\n    message Event {\n      optional string tag = 1;\n      optional string value = 2;\n      optional int64 timeMs = 3;\n    }\n    repeated Statistic stat = 4;\n    message Statistic {\n      required string tag = 1;\n      optional int32 count = 2;\n      optional float sum = 3;\n    }\n    repeated string requestedGroup = 5;\n    optional string cellOperator = 6;\n    optional string simOperator = 7;\n    optional string roaming = 8;\n    optional int32 userNumber = 9;\n  }\n  optional string desiredBuild = 5;\n  optional string locale = 6;\n  optional int64 loggingId = 7;\n  optional string marketCheckin = 8;\n  repeated string macAddress = 9;\n  optional string meid = 10;\n  repeated string accountCookie = 11;\n  optional string timeZone = 12;\n  optional fixed64 securityToken = 13;\n  optional int32 version = 14;\n  repeated string otaCert = 15;\n  optional string serial = 16;\n  optional string esn = 17;\n  repeated string macAddressType = 19;\n  required int32 fragment = 20;\n  optional string userName = 21;\n  optional int32 userSerialNumber = 22;\n}\n\nmessage CheckinResponse {\n  optional bool statsOk = 1;\n  repeated Intent intent = 2;\n  message Intent {\n    optional string action = 1;\n    optional string dataUri = 2;\n    optional string mimeType = 3;\n    optional string javaClass = 4;\n    repeated Extra extra = 5;\n    message Extra {\n      optional string name = 6;\n      optional string value = 7;\n    }\n  }\n  optional int64 timeMs = 3;\n  optional string digest = 4;\n  repeated GservicesSetting setting = 5;\n  message GservicesSetting {\n    optional bytes name = 1;\n    optional bytes value = 2;\n  }\n  optional bool marketOk = 6;\n  optional fixed64 androidId = 7;\n  optional fixed64 securityToken = 8;\n  optional bool settingsDiff = 9;\n  repeated string deleteSetting = 10;\n  optional string versionInfo = 11;\n  optional string deviceDataVersionInfo = 12;\n}\n";
+export declare const mcsRoot: () => Root;
+export declare const checkinRoot: () => Root;

package/dist/transport/push/push-client.d.ts

@@ -0,0 +1,64 @@
+/**
+ * FCM/MCS push client — holds a persistent TLS connection to Google's MCS
+ * (mtalk.google.com:5228), logs in with the check-in androidId/securityToken,
+ * heartbeats, and decodes DataMessageStanza pushes into eufy PushEvents.
+ *
+ * Implements Google's FCM/MCS push protocol; live-verified against real account pushes.
+ */
+import { EventEmitter } from "node:events";
+import type { FcmCredentials, PushEvent, RawPushMessage } from "./types.js";
+import { type Logger } from "../../core/logger.js";
+/**
+ * Normalises a decoded eufy envelope without consulting device semantics; semantic event names remain unset.
+ * @internal
+ */
+export declare function normalizePushEvent(raw: RawPushMessage): PushEvent;
+export declare class PushClient extends EventEmitter {
+    private readonly creds;
+    private readonly logger;
+    /** Consecutive MCS login rejections tolerated (self-healing propagation) before surfacing an error. */
+    private static readonly MAX_LOGIN_FAILURES;
+    private socket?;
+    private readonly parser;
+    private heartbeatTimer?;
+    private reconnectTimer?;
+    private currentDelay;
+    private persistentIds;
+    private loggedIn;
+    private closing;
+    /** Consecutive MCS login rejections — transient ones self-heal via reconnect (see {@link onMessage}). */
+    private loginFailures;
+    constructor(creds: FcmCredentials, logger?: Logger);
+    /** Persistent ids already seen (set this from storage to avoid re-delivery). */
+    setPersistentIds(ids: string[]): void;
+    getPersistentIds(): string[];
+    /**
+     * Open the MCS connection and log in.
+     *
+     * `servername` is passed explicitly: Node sends SNI only when told to, never deriving it from `host`,
+     * and this endpoint answers a connection without SNI with a self-signed certificate naming
+     * `invalid2.invalid` — which now fails the handshake rather than being accepted. Verification matters
+     * because the login request carries the account's `securityToken`, and an unverified peer could both
+     * read it and inject forged pushes into the event path.
+     */
+    connect(): void;
+    private buildLoginRequest;
+    private buildHeartbeatPing;
+    private buildHeartbeatAck;
+    private onMessage;
+    /**
+     * Handle an MCS `LoginResponse` carrying an error. Google occasionally rejects the FIRST login right
+     * after check-in (`wrong_secret`) while the freshly-registered androidId/securityToken propagates —
+     * it succeeds on the very next attempt. So a login rejection is treated as **transient**: log it and
+     * close the socket to let the existing backoff reconnect retry with the same creds, rather than
+     * surfacing a self-healing blip as a host-facing `error`. Only once it persists past
+     * {@link MAX_LOGIN_FAILURES} consecutive attempts (creds genuinely stale) is it emitted as `error`.
+     */
+    private onLoginError;
+    private handleDataMessage;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private onClose;
+    private scheduleReconnect;
+    close(): void;
+}

package/dist/transport/push/store.d.ts

@@ -0,0 +1,23 @@
+import type { FcmCredentials } from "./types.js";
+export interface PersistedPush {
+    creds: FcmCredentials;
+    persistentIds: string[];
+}
+export interface FcmStore {
+    load(): PersistedPush | null;
+    save(p: PersistedPush): void;
+    clear(): void;
+}
+export declare class MemoryFcmStore implements FcmStore {
+    private p;
+    load(): PersistedPush | null;
+    save(p: PersistedPush): void;
+    clear(): void;
+}
+export declare class FileFcmStore implements FcmStore {
+    private readonly path;
+    constructor(path: string);
+    load(): PersistedPush | null;
+    save(p: PersistedPush): void;
+    clear(): void;
+}