@mega-yfue/eufy-sdk 0.5.0-beta.8 → 0.5.0-beta.81

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

@@ -209,6 +209,8 @@ export interface SignedRetry {
 export declare class MegaHttpClient {
     private readonly cfg;
     private region;
+    /** The host `estimate_domain` answered, persisted with the session. */
+    private estimatedDomain;
     private bootstrapDomain?;
     private sessionKey?;
     /** Per-host ECDH session keys for non-mega gateways (e.g. eufylife) keyed by host. */
@@ -228,6 +230,8 @@ export declare class MegaHttpClient {
     /** True while a 2FA code is outstanding: `auth_` holds only the limited pre-verify token, so the
      *  restored-session short-circuit must NOT treat it as a usable session. Cleared on Ok/reset. */
     private pending2fa;
+    /** An autonomous re-login answered captcha/2FA; see {@link canReauthenticate}. */
+    private reloginChallenged;
     private tokenExpiresAt;
     /**
      * Stable per-install device id: `openudid` as configured, as restored from the session store, or as
@@ -259,10 +263,12 @@ export declare class MegaHttpClient {
     constructor(cfg: MegaClientConfig);
     /**
      * Install the session the store holds, if it holds a usable one: the token + its bound ECDH key, skipping
-     * estimate/key-exchange/login/2FA entirely. Answers the token adopted, or `undefined`.
+     * estimate/key-exchange/login/2FA entirely. Answers the token adopted, or `undefined`. A session logged in
+     * with a country other than the configured one is not usable: its shard is the other country's.
      *
      * Read at construction, and again when a rejection is being recovered from — a store SHARED with another
      * client may already hold the session that client obtained, which is cheaper to adopt than to compete with.
+     * An adopted session is a complete one, so it ends any 2FA or challenged re-login this client was left with.
      *
      * Note: the device identity (openudid + phone model + media UA) is NOT restored here — it is resolved once
      * in the constructor, where an explicit config wins over the stored value, and must not be re-derived from a
@@ -275,6 +281,21 @@ export declare class MegaHttpClient {
     } | undefined;
     /** The active region shard (e.g. `"eu-pr"`, `"us-pr"`), set after {@link login} or a region override. */
     get regionShard(): RegionShard;
+    /**
+     * The shard the RTC signalling signs on: the regional prefix of the estimated domain
+     * (`…-ie-…`/`…-ie.` → `ie-pr`), else {@link regionShard}. The eu/us classification cannot name shards
+     * like `ie-pr`, whose accounts need the IE sign host and cluster.
+     */
+    get rtcShard(): string;
+    /**
+     * The credentials the RTC signalling needs; `undefined` while logged out. The sign is refused
+     * ("gtoken not equal userid") unless its gtoken is the one every authed HTTP call carries.
+     */
+    rtcIdentity(): {
+        authToken: string;
+        userId: string;
+        gtoken: string;
+    } | undefined;
     /**
      * The name commands attribute themselves to — {@link MegaClientConfig.accountName} when the config
      * pins one (trimmed; blank counts as unset), otherwise the logged-in account's display name, which
@@ -367,6 +388,15 @@ export declare class MegaHttpClient {
      * params instead, which also carry `{param_type, param_value, update_time}` and are not owner-gated.
      */
     getDeviceParamList<T = unknown>(deviceSn: string): Promise<T>;
+    /**
+     * Fetch the account's devices as the `devicerelation` service lists them, `{attribute: 7, house_id: ""}`.
+     *
+     * Each entry is `{device: {device_sn, dps, …}}`, and `dps` is the cloud's last-known value of every
+     * data point that device has reported, keyed by DP number. Answered for an account a device is shared
+     * with as well as for its owner. Sent with `category: eufy_home`, without which the service answers
+     * `10000`.
+     */
+    getDeviceRelationList<T = unknown>(): Promise<T>;
     /**
      * Fetch one page of a device's **cleaning history** from the mega `clean` service.
      *
@@ -563,7 +593,9 @@ export declare class MegaHttpClient {
      * Structural rather than a list of paths: a login round trip is itself an authenticated call while a limited
      * token is held, so re-logging in from inside one would recurse — and a path list would have to be
      * maintained alongside every request the login flow makes. A 2FA code already outstanding is a login a human
-     * is part-way through, and restarting it silently would discard it. No credentials means nothing to try,
+     * is part-way through, and restarting it silently would discard it. A re-login that already came back needing
+     * a captcha or a 2FA code would need the same again, and each attempt sends the account another code, so
+     * none is tried until a login completes or a stored session is adopted. No credentials means nothing to try,
      * so the rejection surfaces instead.
      */
     private canReauthenticate;

package/dist/transport/mqtt/broker-discovery.d.ts

@@ -8,8 +8,9 @@ export interface BrokerCredentials {
 }
 export interface ProbeResult {
     ip: string;
-    /** True iff SUBSCRIBE to the target topic was granted (qos 0/1/2, not the 0x80 deny code). */
+    /** True iff SUBSCRIBE to the target topic was granted (qos 0/1/2). */
     granted: boolean;
+    /** The SUBACK return code for the topic, the 0x80 deny code included. */
     grantedQos?: number;
     error?: string;
     ms: number;

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

@@ -136,8 +136,9 @@ export declare class MqttCommandRouter {
      * One exception is known: a single garage unit whose own-cert SUBSCRIBE was denied on every candidate
      * while a phone-extracted cert granted on the same one, with a sibling of the same model on the same
      * account granting fine. That is a per-device authorization gap on the vendor's backend, not a
-     * broker-instance problem and not something this SDK works around — such a device reports as offline
-     * (the throw below) until the backend grants the account's own credentials.
+     * broker-instance problem and not something this SDK works around — the throw below names each
+     * candidate's outcome (its SUBACK deny code, a timeout or a connection error) until the backend grants
+     * the account's own credentials.
      *
      * One fresh, explicitly non-reconnecting (`reconnectPeriod: 0`) connection per call — it repays the
      * full mTLS handshake every command and tears the socket down right after (see

package/dist/transport/p2p/audio-frame.d.ts

@@ -0,0 +1,14 @@
+import type { AudioCodec } from "../../core/contracts.js";
+export declare const CMD_AUDIO_FRAME = 1301;
+/** Length of the audio frame header before the payload. */
+export declare const AUDIO_HEADER_LEN = 16;
+/** Byte offset of the codec id between the frame-size and frame-number fields. */
+export declare const AUDIO_TYPE_OFFSET = 5;
+/**
+ * Codec ids the station puts at {@link AUDIO_TYPE_OFFSET}, as the v6 app maps them
+ * (`AudioReader.AAC_LC = 0`, `G711A = 2`, `AAC_ELD = 7`).
+ *
+ * The app's `PCM_SILENCE = -1` is absent on purpose: it is not a wire value. The app injects it
+ * itself when a stream produces no audio at all, to feed its decoder silence.
+ */
+export declare const AUDIO_CODECS: Readonly<Record<number, AudioCodec>>;

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

@@ -111,6 +111,22 @@ export declare function eciesUnwrap(envelope: Buffer, eccPrivateKeyHex: string,
  * Returns the 32-byte key, or undefined if the inputs don't parse.
  */
 export declare function deriveLevel2KeyFromGatewayInfo(gwPayload: Buffer, eccPrivateKeyHex: string): Buffer | undefined;
+/**
+ * Derive the P2P **level-2** AES-128-ECB session key from a *decrypted* `CMD_GATEWAYINFO` (1100)
+ * payload and the RSA private key of a cipher whose `get_ciphers` answer carries no ECC key.
+ *
+ * Layout of the decrypted payload: `cipher_id(2 LE) ‖ 0000 ‖ RSA ciphertext ‖ …`, the ciphertext as
+ * long as the key's modulus. It is the 16-byte session key under PKCS#1 v1.5 encryption padding
+ * (`00 02 ‖ ≥8 non-zero bytes ‖ 00 ‖ key`). The padding is checked here over the raw RSA result so a wrong
+ * key fails closed: under OpenSSL's implicit rejection, `RSA_PKCS1_PADDING` answers random bytes for it
+ * instead of throwing, and those can be 16 bytes long.
+ *
+ * `rsaPrivateKey` is the `get_ciphers` `private_key`: base64 PKCS#8 DER.
+ *
+ * Returns the 16-byte key, or `undefined` when the key does not parse, the payload is short, or the
+ * padding or key length is wrong (fails closed, never throws).
+ */
+export declare function deriveLevel2KeyFromRsaGatewayInfo(gwPayload: Buffer, rsaPrivateKey: string): Buffer | undefined;
 /** Local-lookup payload: two zero bytes. */
 export declare function buildLocalLookupPayload(): Buffer;
 /** Cloud-lookup payload (variant 2): `[p2pDid:20][dskKey][0x00000000]`. */

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

@@ -1,14 +1,3 @@
-/**
- * P2P command router — the transport-side owner of the ThroughTek PPCS sessions and every wire
- * operation over them: opening sessions, resolving a serial to its session + routing params,
- * mapping a transport-neutral {@link Command} to a concrete frame (encryption level, wire shape),
- * the fire-and-forget control senders, request/reply queries, and the media provider.
- *
- * Layering: this module knows P2P bytes; it does NOT know capabilities. Frame → semantic-event
- * decoding is a model concern, so raw frames are handed back to the client via {@link P2PRouterDeps.onFrame}
- * (the client gates them on device capabilities and emits typed events). This keeps transport free of
- * any `model/` import — the capability↔transport decorrelation invariant.
- */
 import type { MegaHttpClient } from "../http/mega-client.js";
 import type { EufyDevice } from "../../core/types.js";
 import type { Command, AutoLockSnapshot, MediaProvider, SharedSourceHints, AbortableCall } from "../../core/contracts.js";
@@ -119,7 +108,7 @@ export declare class P2PCommandRouter {
      * shared — see {@link P2PCommandRouter.openTalkback}.
      */
     private readonly talkbacks;
-    /** cipher_id → ECC private key (one eufylife get_ciphers call per cipher), shared across (re)opens. */
+    /** cipher_id → its ECC and RSA private keys (one eufylife get_ciphers call per cipher), shared across (re)opens. */
     private readonly cipherKeyCache;
     /** The recording download in flight per station; a station serves one at a time. */
     private readonly recordingDownloads;
@@ -224,7 +213,7 @@ export declare class P2PCommandRouter {
      * Build + wire a {@link P2PSession} for a station (NOT yet connected — the caller awaits `connect()`).
      *
      * `resolveCipherKey` auto-negotiates the level-2 session key from `CMD_GATEWAYINFO` by resolving the
-     * cipher's ECC private key via cloud `get_ciphers`, so signCode 2/8 frames decrypt live; results are
+     * cipher's private keys via cloud `get_ciphers`, so signCode 2/8 frames decrypt live; results are
      * cached on the router instance so a lazy re-open (after idle-detach) reuses the lookup. Only a
      * SUCCESSFUL lookup is cached — caching `undefined` after a transient failure would permanently
      * disable level-2 for the session's life.
@@ -240,11 +229,12 @@ export declare class P2PCommandRouter {
      */
     private makeSession;
     /**
-     * The ECC private key of `cipherId`, from the router's cache or one `get_ciphers` call. When the cloud
-     * answers with another cipher, that one is used and traced on `session`. Only a successful lookup is
-     * cached.
+     * The ECC and RSA private keys of `cipherId` (`ecc_private_key`, `private_key`), from the router's cache
+     * or one `get_ciphers` call. When the cloud answers with another cipher that carries an ECC key and the
+     * asked one does not, that one is used and traced on `session`. Only a successful lookup — one that
+     * yields either key — is cached.
      */
-    private cipherKeyFor;
+    private cipherKeysFor;
     /**
      * Open (or reuse) a station's P2P session and await its completed handshake. An optional abort only
      * stops this wait; session ownership remains with {@link SessionManager} and its normal teardown.
@@ -311,6 +301,11 @@ export declare class P2PCommandRouter {
      * stream costs nothing extra and a talkback on an otherwise idle camera opens the session it needs
      * instead of playing into silence.
      *
+     * **On a model in {@link ELD_TALKBACK_MODELS}, the speaker plays the codec the camera sends.** So the first
+     * audio frame of the media session this talkback holds decides its codec ({@link speakerCodec}), within
+     * {@link TALKBACK_CODEC_WAIT_MS} of the session's first frame, and the claim is re-checked after that wait as
+     * after the warm-up. Every other model opens `aac-lc` at once.
+     *
      * The level-2 key is waited for softly: only the HomeBase-attached path requires it, and
      * {@link Talkback.start} reports that failure precisely, so a hard wait here would reject an
      * own-session camera that legitimately never negotiates one.
@@ -456,15 +451,6 @@ export declare class P2PCommandRouter {
      * A still with no live sibling re-asserts, so a tile refreshing on a quiet station is
      * unaffected.
      */
-    /**
-     * Attach a consumer, unless the caller has already abandoned the call.
-     *
-     * The acquisition it just waited through can outlast the caller's interest, and a consumer attached for
-     * somebody who has gone keeps the pull warm for nobody. Detaching immediately gives the pull back, which
-     * lets it linger and fall away if this was the only thing holding it, and leaves it untouched if it was
-     * not.
-     */
-    private attachUnlessAborted;
     /**
      * Dispose one cached live source and forget it, so the next acquisition builds a fresh one. Its claim
      * on a session goes with it, and a media session opened for this source alone is closed: nothing else
@@ -524,11 +510,11 @@ export declare class P2PCommandRouter {
      */
     private onLiveStartFailed;
     /**
-     * Replace the session under a warming source whose media start nothing acknowledged, and warm again on it.
+     * Replace the session under a warming source it is not serving, and warm again on it.
      *
      * Only a STANDALONE device's session is replaced, for the reason {@link onLiveStartFailed} gives: an attached
      * camera shares its HomeBase session with every other camera on it, and closing that to recover one would
-     * drop the rest. Such a source keeps the re-issue it always had.
+     * drop the rest. Such a source keeps the re-issue it always had, which the answer (false) tells it.
      *
      * The source is left warming throughout, holding the deadline it started, so this either produces a stream
      * within that window or fails exactly as it would have. A replacement that cannot be opened leaves the
@@ -562,6 +548,7 @@ export declare class P2PCommandRouter {
      */
     p2pQuery(sn: string, subCmd: number, opts?: {
         timeoutMs?: number;
+        payload?: Record<string, unknown>;
     }): Promise<Record<string, unknown>>;
     /**
      * **Generic control-payload request/reply query.** Sends a `CONTROL_PAYLOAD` (1700) `{commandType,
@@ -690,7 +677,7 @@ export declare class P2PCommandRouter {
      * **`set-json-raw` intent** — bare JSON, no envelope: outer P2P cmd = `outerCmd` itself, plaintext
      * exactly `{account_id,...data}` (`session.sendRawLevel2` with no wrapper). Reversed from a live
      * capture of the app's own SET_SNOOZE_TIME (1271) frame — see `param-dictionary.ts`'s `1271` entry
-     * (`snoozeTime`); the alarm-delay config (1255, `arming.ts`'s `ARMING_CMD.ALARM_DELAY_CONFIG`) reuses
+     * (`snoozeTime`); the alarm-delay config (1255, `arming.ts`'s `ARMING_CMD.SET_ALL_ACTION`) reuses
      * the same bare-JSON shape.
      */
     private sendJsonRaw;
@@ -705,7 +692,9 @@ export declare class P2PCommandRouter {
      * HomeBase-attached device takes the GCM signCode-8 form, a standalone one the level-1 form. A
      * standalone camera never negotiates a level-2 key, so pinning this to level 2 makes the envelope
      * unreachable on exactly the devices that serve their own RTSP stream. Verified live: a standalone
-     * camera accepts the level-1 form. With no `form` (default) it stays level-2 only.
+     * camera accepts the level-1 form. With no `form` (default) it stays level-2 only and waits for the
+     * key every level-2 sender uses; `level2Sender: "set-payload"` also takes an RSA cipher's AES-128-ECB
+     * key (see {@link P2PSession.sendControlLevel2}). A `resolved` session keeps the wait its caller gave it.
      *
      * Both seals REPLAY the frame {@link DIRECT_CMD_SENDS}× at 200ms, as every other fire-and-forget
      * control on this router does: these are unacknowledged datagrams, and a level-1 device is the one

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

@@ -17,9 +17,12 @@ export declare class Fmp4Muxer {
     private baseDecodeTime;
     private fragTicks;
     private samples;
-    private lastVideoTimestampMs?;
+    /** Ticks from the first video sample's start to the newest sample's end, at its provisional duration. */
+    private videoTicks;
     private readonly audioRequested;
     private audioCodec?;
+    /** Decoder config of an AAC-ELD track, taken from its frames; absent for AAC-LC, whose `esds` config is fixed. */
+    private audioConfig?;
     private audioDisabled;
     private audioSamples;
     private audioBaseDecodeTime;
@@ -35,9 +38,16 @@ export declare class Fmp4Muxer {
      * Push one access unit. Returns any completed segments: the `init` on the first keyframe, and/or a
      * media fragment when this frame closed the open one. Returns `undefined` if nothing is emitted yet
      * (e.g. delta frames before the first keyframe).
+     *
+     * A sample lasts until the next frame's `timestampMs`, measured from the first keyframe's, so the video
+     * timeline follows the arrival clock; a frame that shares the previous one's timestamp leaves that
+     * sample one tick long, and the next frame's duration absorbs the difference.
      */
     push(frame: LiveVideoFrame, timestampMs?: number): MediaFragment | undefined;
-    /** Add one station-declared AAC access unit to the audio track. G.711 remains available via `live()`. */
+    /**
+     * Add one station-declared AAC access unit to the audio track: an ADTS frame for AAC-LC, a raw access unit
+     * described by its frame's config for AAC-ELD. G.711 remains available via `live()`.
+     */
     pushAudio(frame: LiveAudioFrame, timestampMs?: number): MediaFragment | undefined;
     /** Permanently omit incompatible audio while allowing the video recording to continue. */
     private disableAudio;

package/dist/transport/p2p/live-trace.d.ts

@@ -11,6 +11,7 @@
  *
  * @module p2p/live-trace
  */
+import type { LiveStreamStartFailureReason, LiveStreamStartStage } from "../../core/contracts.js";
 import type { Logger } from "../../core/logger.js";
 /** The message every startup trace is logged under. */
 export declare const LIVE_TRACE_MESSAGE = "[live] start trace";
@@ -118,11 +119,19 @@ export type LiveTrace =
     phase: "level2-wait";
     waitMs: number;
 }
-/** The station's level-2 key was negotiated, under the cipher it selected. */
+/** The station's AES-256-GCM level-2 key was negotiated, under the cipher it selected. */
  | {
     phase: "level2-ready";
     cipherId: number;
 }
+/**
+ * The station's cipher negotiated only the AES-128-ECB level-2 key of an RSA cipher, under the cipher it
+ * selected. That key seals a level-2 set-payload and nothing else, so this is not `level2-ready`.
+ */
+ | {
+    phase: "level2-set-payload-only";
+    cipherId: number;
+}
 /**
  * The station's key is not coming, why, and the cipher where a station named one.
  *
@@ -145,7 +154,8 @@ export type LiveTrace =
  * A station's cipher was answered with material for a DIFFERENT cipher, which was used in its place.
  *
  * The one lookup outcome no other phase accounts for: material for the cipher the station named is followed
- * by `level2-ready` or by `level2-unavailable` with `derivation-failed`, an answer holding none by
+ * by `level2-ready`, `level2-set-payload-only` or `level2-unavailable` with `derivation-failed`, an answer
+ * holding none by
  * `no-cipher-key`, and a lookup that threw is reported as an error. Substituted material derives to
  * nothing and otherwise reads as a station fault. `cipherId` is the cipher the station asked for,
  * `answeredCipherId` the one whose material was used.
@@ -236,6 +246,19 @@ export type LiveTrace =
     phase: "channel-silent";
     silentMs: number;
     outcome: "reasserted" | "declined";
+}
+/**
+ * A live start failed, with the facts of the `LiveStreamStartError` it was refused with.
+ *
+ * `errorName` is the upstream error's class name, present for `source-error` only; its message is never
+ * carried, because an upstream message can name a station.
+ */
+ | {
+    phase: "start-failed";
+    reason: LiveStreamStartFailureReason;
+    stage: LiveStreamStartStage;
+    attempts: number;
+    errorName?: string;
 };
 /**
  * Record one startup observation at debug level.

package/dist/transport/p2p/p2p-session.d.ts

@@ -46,12 +46,18 @@ export interface P2PSessionConfig {
     /** Disable UDP broadcast local lookup (e.g. cloud-only). Default false. */
     noBroadcast?: boolean;
     /**
-     * Resolve a station `cipher_id` → its ECC private key hex (from cloud `get_ciphers`). When
-     * provided, the session auto-negotiates the **level-2** session key on connect: it reads the
-     * `cipher_id` + ECIES envelope from the `CMD_GATEWAYINFO` reply, derives the key, and calls
-     * `setLevel2Key()` — so signCode 2/8 frames (camera info, event DB, event images) decrypt live.
-     */
-    resolveCipherKey?: (cipherId: number) => Promise<string | undefined>;
+     * Resolve a station `cipher_id` → its private keys (from cloud `get_ciphers`): `ecc`, the ECC private
+     * key hex (`ecc_private_key`), and `rsa`, the RSA private key (`private_key`). A plain string is the ECC key. Called once per
+     * negotiation. When provided, the session auto-negotiates the **level-2** session key on connect: it
+     * reads the `cipher_id` + envelope from the `CMD_GATEWAYINFO` reply and derives the key. With an ECC
+     * key that is the ECIES unwrap and `setLevel2Key()` — so signCode 2/8 frames (camera info, event DB,
+     * event images) decrypt live. A cipher with no ECC key carries the key RSA-encrypted instead, and only
+     * {@link P2PSession.sendControlLevel2} seals with it.
+     */
+    resolveCipherKey?: (cipherId: number) => Promise<string | {
+        ecc?: string;
+        rsa?: string;
+    } | undefined>;
     /** Diagnostics sink. Omit for silence. */
     logger?: Logger;
 }
@@ -149,6 +155,12 @@ export declare class P2PSession extends EventEmitter {
     private readonly level1Key;
     /** Negotiated 32-byte level-2/gateway key (AES-256-GCM). Set via setLevel2Key once known. */
     private level2Key?;
+    /**
+     * Negotiated 16-byte level-2 key of a cipher with no ECC key (RSA-encrypted in `CMD_GATEWAYINFO`). Only
+     * {@link sendControlLevel2} seals with it, AES-128-ECB in the level-1 layout at encryption type 2; never
+     * held beside {@link level2Key}.
+     */
+    private level2EcbKey?;
     private level2Seq;
     private rsaPrivateKey?;
     private rsaModulusHex?;
@@ -204,10 +216,18 @@ export declare class P2PSession extends EventEmitter {
     private trace;
     /** Provide the negotiated 32-byte session key so level-2 (signCode 2/8) frames can be decrypted. */
     setLevel2Key(key: Buffer): void;
-    /** Whether the level-2 session key has been negotiated/set. */
+    /** Whether the AES-256-GCM level-2 session key has been negotiated/set. */
     get hasLevel2Key(): boolean;
+    /**
+     * Whether the held level-2 key can frame for `sender`: every level-2 sender needs the AES-256-GCM key,
+     * and `"set-payload"` ({@link sendControlLevel2}) also takes the AES-128-ECB key of an RSA cipher.
+     */
+    private level2KeyServes;
     /**
      * Resolve with whether a level-2 key is available, waiting only while waiting can still change that.
+     * `sender` names who will frame with it: by default every level-2 sender, which needs the AES-256-GCM
+     * key; `"set-payload"` is {@link sendControlLevel2} alone, which also takes the AES-128-ECB key of an RSA
+     * cipher, so `true` for it does not imply {@link hasLevel2Key}.
      *
      * A `"session"` grace is measured once, not restarted per call. Best-effort media uses it because every
      * egress asks this same session and can proceed without the key on an own-session camera; a per-call
@@ -232,7 +252,7 @@ export declare class P2PSession extends EventEmitter {
      * `terminal` outcome is the one already stated where the negotiation concluded, since that is where the
      * cipher and the cause are known, and re-stating it here would double every settled negotiation.
      */
-    awaitLevel2Key(graceMs: number, graceFrom?: "call" | "session"): Promise<boolean>;
+    awaitLevel2Key(graceMs: number, graceFrom?: "call" | "session", sender?: "every" | "set-payload"): Promise<boolean>;
     /**
      * Ask the station for its gateway info a second time, re-opening a negotiation that concluded without a key.
      *
@@ -253,9 +273,12 @@ export declare class P2PSession extends EventEmitter {
     private settleLevel2;
     /**
      * Negotiate the level-2 session key from the decrypted CMD_GATEWAYINFO payload: read its
-     * `cipher_id`, resolve that cipher's ECC private key (cloud `get_ciphers`, via the configured
-     * `resolveCipherKey`), run the ECIES unwrap, and `setLevel2Key()`. One-shot; emits `level2Ready`
-     * on success and `error` on failure (non-fatal — level-1 traffic keeps working regardless).
+     * `cipher_id`, resolve that cipher's private keys once (cloud `get_ciphers`, via the configured
+     * `resolveCipherKey`), run the ECIES unwrap with the ECC key, and `setLevel2Key()`. A cipher with no
+     * ECC key uses its RSA key instead and holds the RSA-decrypted 16-byte key as the AES-128-ECB level-2
+     * key. One-shot; emits `level2Ready` only when the AES-256-GCM key is negotiated, traces
+     * `level2-set-payload-only` instead for the AES-128-ECB key, and emits `error` on failure
+     * (non-fatal — level-1 traffic keeps working regardless).
      *
      * Every outcome settles the wait in {@link awaitLevel2Key}, because being one-shot is what makes a
      * failure final for this connection generation: nothing will retry it there, so a later command must be
@@ -421,6 +444,10 @@ export declare class P2PSession extends EventEmitter {
      * mechanism proven for camera selection in media start. Use for control commands routed through a
      * HomeBase (where level-1 ECB is rejected). Returns `false` if the level-2 key isn't negotiated
      * yet (caller can fall back to {@link sendStringPayloadCommand}).
+     *
+     * On a session holding only the AES-128-ECB level-2 key of an RSA cipher, the frame is the level-1
+     * layout ({@link sendRawLevel1Bytes}) sealed under that key at encryption type 2: the encryption-type
+     * byte names the key the body is sealed with (1 = level-1 key, 2 = the negotiated key).
      */
     sendControlLevel2(cmd: number, channel: number, accountId: string, payload: Record<string, unknown>, mValue3?: number): boolean;
     /**
@@ -611,6 +638,18 @@ export declare class P2PSession extends EventEmitter {
         accountId?: string;
         channel?: number;
     }): void;
+    /**
+     * Read a date-ranged page of `history_record_info` from the station. The reply's `data` array groups
+     * recording rows with companion tables; each group retains its `table_name` and `payload`.
+     * `startTime` is `"0"` for the newest page or the oldest row's `yyyyMMddHHmmss` cursor for older rows.
+     */
+    queryRecordPage(opts: {
+        accountId?: string;
+        startDate: string;
+        endDate: string;
+        startTime?: string;
+        count?: number;
+    }): Promise<unknown[]>;
     /**
      * Query one on-station table and answer its rows, once the reply is whole.
      *
@@ -618,13 +657,15 @@ export declare class P2PSession extends EventEmitter {
      * several frames whose decrypted text is a fragment of one document, so the fragments are
      * accumulated here and scanned after each one. Answers that document's `data` rows. Rejects when
      * `signal` aborts, and when `timeoutMs` (default {@link DB_TABLE_TIMEOUT_MS}) elapses with no
-     * complete reply.
+     * complete reply, and when the station answers a non-zero `mIntRet`.
      *
      * One read at a time per session: while one is accumulating, every {@link queryDatabase} on the
      * session throws, so a second reply cannot land in this buffer.
      */
     readDatabase(table: string, opts?: {
         accountId?: string;
+        innerCmd?: number;
+        query?: Record<string, unknown>;
         timeoutMs?: number;
         signal?: AbortSignal;
     }): Promise<unknown[]>;
@@ -704,6 +745,7 @@ export declare class P2PSession extends EventEmitter {
      * Frames are packed back to back, so a frame header can itself be cut by a datagram boundary. The start
      * of a header left at the end of a datagram is carried into the next one rather than discarded; dropping
      * it would lose that frame and every frame after it until a datagram happened to begin on a header.
+     * Payload fragments retain their original slices and are copied once, when the complete frame is delivered.
      */
     private reassemble;
     /**
@@ -718,5 +760,6 @@ export declare class P2PSession extends EventEmitter {
     private ackTypeHeader;
     private handleFrame;
     private send;
+    /** Finish the END send on the current socket before closing it; send completion is not a peer ACK. */
     close(): Promise<void>;
 }

package/dist/transport/p2p/readable-egress.d.ts

@@ -17,11 +17,15 @@ import type { Consumer } from "./shared-live-source.js";
 export interface ReadableEgressOptions {
     /** Emit {@link LiveVideoFrame} objects instead of raw Annex-B bytes (default false = bytes). */
     objectMode?: boolean;
+    /** Yield ReceivedVideoFrame envelopes with original source-arrival times; ignored in raw mode. */
+    arrivalTime?: boolean;
     /** Readable highWaterMark (bytes, or object count in objectMode). */
     highWaterMark?: number;
 }
 /**
  * Wrap a shared-source {@link Consumer} in a fresh Readable. The consumer is detached when the
  * Readable is destroyed/ended, so callers own the lifetime by owning the stream.
+ * Frames arrive through onMedia; an empty video listener releases the keyframe-prime
+ * because ConsumerImpl replays it when the first video listener is added.
  */
 export declare function openReadableFromConsumer(consumer: Consumer, opts?: ReadableEgressOptions): Readable;

package/dist/transport/p2p/recording-download.d.ts

@@ -46,9 +46,10 @@ export declare function receiveRecording(session: P2PSession, request: {
     signal?: AbortSignal;
 }): RecordingTransfer;
 /**
- * Decode a recording's frames, in arrival order, into elementary streams. Keyframes go through one
- * {@link VideoFrameDecoder}, whose media key then opens the audio; a keyframe that does not open under
- * `eccPrivateKeyHex`, and every audio frame before the first media key, are dropped. Rejects with
+ * Decode a recording's frames, in arrival order, into elementary streams. Split pictures are assembled
+ * before they enter the output; an orphan continuation cannot become its own picture. Keyframes go
+ * through one {@link VideoFrameDecoder}, whose media key then opens the audio; a keyframe that does not
+ * open under `eccPrivateKeyHex`, and every audio frame before the first media key, are dropped. Rejects with
  * {@link RecordingDownloadError} `undecodable` when no video frame decodes.
  */
 export declare function decodeRecording(frames: readonly RecordingFrame[], eccPrivateKeyHex: string): RecordingDownload;

package/dist/transport/p2p/shared-live-source.d.ts

@@ -83,12 +83,13 @@ export interface SharedLiveSourceOptions {
      */
     onStopped?: () => void;
     /**
-     * A media start was abandoned unacknowledged before anything was delivered, so this session is not being
-     * heard. The owner is asked for a replacement and calls {@link SharedLiveSource.rewarm} once it has one.
+     * This session is not serving the warm-up: a media start was abandoned unacknowledged, or forced starts went
+     * unanswered by any media, before anything was delivered. The owner answers whether it is replacing the
+     * session, and calls {@link SharedLiveSource.rewarm} once it has the replacement.
      *
-     * Asked at most once per warm-up: further abandonments are the same session saying the same thing.
+     * Asked at most once per warm-up: further evidence is the same session saying the same thing.
      */
-    onSessionUnreachable?: () => void;
+    onSessionUnreachable?: () => boolean;
 }
 /**
  * A single consumer of a {@link SharedLiveSource}. A {@link LiveStreamConsumer} (so `live()` can hand it
@@ -251,18 +252,17 @@ export declare class SharedLiveSource {
      */
     private warm;
     /**
-     * A start was abandoned unacknowledged. Ask for a replacement session where nothing has been delivered yet.
+     * Ask the owner for a replacement session where nothing has been delivered yet, answering whether one is coming.
      *
-     * The abandonment is roughly twenty byte-identical sends with no reply, against acknowledgement latencies of
-     * 4–37 ms awake and 238 ms waking, so it is the session that is not being heard rather than a slow device —
-     * `P2PSession` says as much: the camera was never told to stream, so this warm-up can only time out. Where
-     * media has already flowed the abandonment means something else and this does nothing.
+     * An unacknowledged start is roughly twenty byte-identical sends with no reply, against acknowledgement latencies
+     * of 4–37 ms awake and 238 ms waking, so it is the session that is not being heard rather than a slow device: the
+     * camera was never told to stream. Where media has already flowed the abandonment means something else and this
+     * does nothing. The DEADLINE is left running: the window belongs to the attempt, not to the session it started on.
      *
-     * The retry ticker is stopped while a replacement is awaited, because every tick it issues goes to the same
-     * unheard session. The DEADLINE is left running: the window belongs to the attempt, not to the session it
-     * started on.
+     * The retry ticker is stopped only once the owner has said it is replacing the session: an owner that cannot
+     * (an attached camera shares its HomeBase session) leaves the source re-issuing as it always did.
      */
-    private onStartUnacknowledged;
+    private askForFreshSession;
     /**
      * Warm again on a session the owner has replaced, inside the deadline the first attempt started.
      *
@@ -290,6 +290,11 @@ export declare class SharedLiveSource {
      * {@link fruitlessReissues} for why one is not enough and why what the stream delivered earlier is not
      * evidence. Once media arrives the keepalive is what is wanted, and an attached camera re-sends a full start
      * either way.
+     *
+     * A forced start that a whole interval later has still produced nothing is a session that acknowledges and
+     * does not serve: a fresh session on the same camera delivers a keyframe within a second, so a warm-up asks
+     * for one rather than forcing starts onto this one until its deadline. Wired only: a cold battery camera is
+     * slow rather than deaf, measured at about 8 s to first media, and replacing its session would cost a wake.
      */
     private reissueStart;
     /**
@@ -338,7 +343,8 @@ export declare class SharedLiveSource {
      * at all, audio without a single video frame, or access units a decoder cannot begin at.
      *
      * Video takes precedence when both arrived: audio alongside video says nothing a caller needs, while video
-     * without a keyframe does.
+     * without a keyframe does. Every failed start is built here, so this is where its `start-failed` trace is
+     * emitted.
      */
     private startFailure;
     private onVideo;
@@ -438,3 +444,12 @@ export declare class SharedLiveSource {
      */
     dispose(): void;
 }
+/**
+ * Attach a consumer, unless the caller has already abandoned the call.
+ *
+ * The acquisition it just waited through can outlast the caller's interest, and a consumer attached for
+ * somebody who has gone keeps the pull warm for nobody. Detaching immediately gives the pull back, which
+ * lets it linger and fall away if this was the only thing holding it, and leaves it untouched if it was
+ * not.
+ */
+export declare function attachUnlessAborted(source: SharedLiveSource, signal?: AbortSignal): Consumer;