@mega-yfue/eufy-sdk 0.2.0-beta.2 → 0.2.0-beta.21

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

@@ -67,7 +67,7 @@ export interface LiveStreamOptions {
      * How long an attached stream tolerates silence on its own channel before re-asserting again, in ms.
      *
      * The re-assert is settled by the first own-channel frame, because settling it is what stops two attached
-     * streams contending on a station that serves one camera at a time. Silence for this long says the station
+     * streams contending over one session, which serves one camera at a time. Silence for this long says the station
      * is no longer serving this camera, which is the only condition the re-assert was for. Defaults to twice
      * the keepalive interval, so a stream whose media flows never reaches it.
      */
@@ -129,8 +129,9 @@ export declare class LiveStream extends EventEmitter {
      * Stop re-issuing the media start once this camera's own media has arrived, on an attached camera.
      *
      * The nudge differs by topology and only one branch is a ping: an own-session camera sends a small
-     * keepalive, while an attached camera has no such state and re-sends the FULL media start. On a station that
-     * serves one camera at a time that restart re-asserts this channel against whatever else is warm, so two
+     * keepalive, while an attached camera has no such state and re-sends the FULL media start. Over one session,
+     * which serves one camera at a time, that restart re-asserts this channel against whatever else is warm on
+     * it, so two
      * attached streams restart every interval and contend for the station continuously — measured on a real base
      * as a full start every 3 s from each.
      *
@@ -185,7 +186,7 @@ export declare class LiveStream extends EventEmitter {
      *
      * The match is UNCONDITIONAL, however long a station serves another camera instead of this one.
      *
-     * A station serving one camera at a time hands a newly opened camera nothing but its sibling's frames until
+     * One session serving one camera at a time hands a newly opened camera nothing but its sibling's frames until
      * it switches, so "no media of my own yet, plenty for someone else" is what an ordinary handover looks like
      * and does not distinguish a station that tags differently from one that is simply busy.
      *

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

@@ -63,12 +63,51 @@ export type LiveTrace =
     phase: "sequence-restart";
     dataType: number;
 }
+/**
+ * Which lookup channels a connection can ask for the station on, before it asks.
+ *
+ * A station is found by a local lookup, by a cloud lookup, or by both, and each needs something the other
+ * does not: the local one needs the station on this link, the cloud one needs both a key for the station and
+ * an address to ask. A connect that had one channel failed for that channel's reason alone, and a connect
+ * that had neither could not have succeeded — outcomes a station that is switched off is otherwise
+ * indistinguishable from, because nothing else in a failed connect states what was even attempted.
+ */
+ | {
+    phase: "lookup-channels";
+    local: boolean;
+    cloud: boolean;
+}
+/**
+ * Work on a station is holding for its session to connect, with the milliseconds it will wait.
+ *
+ * The earliest phase there is: nothing else on a station can be attempted until its session is up, and a
+ * caller whose own deadline expires inside this wait has this record and no other. Emitted only where a wait
+ * actually happens, so its absence states that the session was already connected.
+ */
+ | {
+    phase: "session-connect-wait";
+    waitMs: number;
+}
+/** The session connected, after this long. */
+ | {
+    phase: "session-connected";
+    waitedMs: number;
+}
+/**
+ * The session did not connect within its wait, so nothing on this station can be attempted.
+ *
+ * The one outcome that is otherwise indistinguishable from a station that answered and then refused: both
+ * leave a caller with no media and no phase naming a station.
+ */
+ | {
+    phase: "session-unreachable";
+    waitedMs: number;
+}
 /**
  * A live start is holding for the station's level-2 key, with the milliseconds it will wait.
  *
- * The first of three phases that account for the wait before any media command is sent. A start that looks
- * slow is either waiting here, waiting for the station to serve the channel it was asked for, or being
- * re-issued — and only these separate them.
+ * A start that looks slow is either waiting here, waiting for its session to connect, waiting for the station
+ * to serve the channel it was asked for, or being re-issued — and only these phases separate them.
  */
  | {
     phase: "level2-wait";
@@ -79,10 +118,67 @@ export type LiveTrace =
     phase: "level2-ready";
     cipherId: number;
 }
-/** The level-2 key did not arrive in its grace, so the start proceeds at level 1 or not at all. */
+/**
+ * The station's key is not coming, why, and the cipher where a station named one.
+ *
+ * Every ending of a level-2 wait carries one of these reasons, so a start refused for want of a key is
+ * accounted for however it ended. `grace-elapsed` is a wait that ran out and states how long was waited;
+ * the rest are answered without waiting, because the negotiation is one-shot per connection and a
+ * concluded one is final. `no-cipher-key` and `derivation-failed` are about this account's cipher
+ * material, `not-negotiating` and `session-closed` about the station or its connection — and only a
+ * reason reached under a negotiation has a cipher to name.
+ *
+ * A `grace-elapsed` start proceeds at level 1 where it has such a form, and not at all where it does not.
+ */
  | {
-    phase: "level2-absent";
-    waitedMs: number;
+    phase: "level2-unavailable";
+    reason: "no-cipher-key" | "derivation-failed" | "not-negotiating" | "session-closed" | "grace-elapsed";
+    cipherId?: number;
+    waitedMs?: number;
+}
+/**
+ * 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
+ * `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.
+ */
+ | {
+    phase: "cipher-fallback";
+    cipherId: number;
+    answeredCipherId: number;
+}
+/**
+ * The station answered its gateway-info prompt, so a key derivation has begun under the cipher it named.
+ *
+ * What separates a station that never answered the prompt from one that answered and produced no usable key:
+ * without it, `level2-unavailable` with `not-negotiating` covers both, and they are a station or network
+ * problem and an account cipher-material problem respectively.
+ */
+ | {
+    phase: "level2-negotiating";
+    cipherId: number;
+}
+/**
+ * A station was resolved for a call, stating what the caller's device is on it and whose station it is.
+ *
+ * Emitted before the session is waited on, so a station that is never reached still has this record: an
+ * attached camera's media start has no unencrypted form, so whether a device was taken as attached decides
+ * what its failure means. `stationAdmin` states whether the signed-in account is the station's
+ * administrator, which is what a key the account cannot resolve turns on; `unstated` is a device record
+ * that names no administrator, which is not the same as naming another. `stationModel` is the model of the
+ * station the call resolved — the base's for an attached camera, the device's own where it is its own
+ * station — absent where that record states none; without it a base this SDK reaches differently is
+ * indistinguishable from one that is switched off.
+ */
+ | {
+    phase: "station-resolved";
+    topology: "attached" | "own";
+    channel: number;
+    stationAdmin: "self" | "other" | "unstated";
+    stationModel?: string;
 }
 /** A shared source began warming, with the interval it re-issues on and the deadline it fails at. */
  | {
@@ -110,6 +206,22 @@ export type LiveTrace =
  | {
     phase: "path-stale";
     silentMs: number;
+}
+/**
+ * A stream received nothing on its own channel for the stall window, and what was done about it.
+ *
+ * A station that switches to a sibling leaves the stream it was serving with no frames, no error and no
+ * stop, so this silence is the only statement that it happened. `reasserted` re-issued the media start,
+ * which is the repair; `declined` left the channel alone because nothing is attached to this pull and
+ * taking the station back would take it from a camera someone is watching.
+ *
+ * Media still arriving means this never fires, so a picture that stopped advancing while this is silent
+ * stopped for a reason upstream of the station's attention.
+ */
+ | {
+    phase: "channel-silent";
+    silentMs: number;
+    outcome: "reasserted" | "declined";
 };
 /**
  * Record one startup observation at debug level.

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

@@ -34,11 +34,22 @@ export declare function openLiveStream(session: P2PSession, opts?: LiveStreamOpt
  * The header states the stream's geometry when the capture started, and a stream that reconfigures
  * mid-burst leaves it describing something the returned bytes contradict; the return value describes an
  * image, so the image is its source of truth.
+ *
+ * The consumer is detached the moment the collected run is complete, and the decode that follows holds no
+ * station: it works on bytes already in memory. One session serves one camera at a time and a still never
+ * opens a second one, so a still that kept its pull attached across its own decode would deny
+ * that station to every live request for the length of an FFmpeg run — measured on a real base as a live
+ * request refused 370ms after the still it was waiting on had already collected everything it needed.
+ *
+ * `signal` ends the collection itself, not only the wait for it, and rejects with the signal's own reason
+ * because the abandonment is the caller's fact and not a failure of the source. It reaches only the
+ * collection: past that the station is already free, so there is nothing left for it to release.
  */
 export declare function captureSnapshotFromShared(source: SharedLiveSource, opts?: {
     timeoutMs?: number;
     collectMs?: number;
     skipKeyframes?: number;
+    signal?: AbortSignal;
     logger?: Logger;
     ffmpegLevel?: FfmpegLevel;
     ffmpegPath?: string;

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

@@ -16,6 +16,15 @@
 import { EventEmitter } from "node:events";
 import { type Address, type P2PDataFrameHeader } from "./codec.js";
 import { type Logger } from "../../core/logger.js";
+/**
+ * How long a station is given to answer a lookup before the connection gives up on it and closes.
+ *
+ * The whole deadline for reaching a station: the lookups are re-sent every second until one is answered, and
+ * a connection that reaches this closes itself, so nothing addressed to that station can succeed afterwards.
+ * Published because it bounds every wait on a session connecting — a second number for the same deadline
+ * elsewhere would outlive the connection it waits on and charge the difference to every failure.
+ */
+export declare const CONNECT_TIMEOUT_MS = 15000;
 /**
  * The channel a command addresses the station itself on, rather than one of its cameras, and the value a
  * session's channel-taking methods resolve an omitted channel to.
@@ -208,6 +217,10 @@ export declare class P2PSession extends EventEmitter {
      * cameras from that second group streamed normally at level-1 — including one of the same firmware as an
      * own-session camera that delivered no video at all for a reason of its own. An expired grace therefore
      * separates nothing on this path, and a start failure on such a session is not evidence about it.
+     *
+     * Every `false` answer carries a `level2-unavailable` trace naming its reason, wherever the wait ended: a
+     * `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>;
     /**

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

@@ -26,24 +26,35 @@ export interface SessionManagerOpts {
     batteryIdleMs?: number;
     /** Keepalive a single command holds after dispatch (ms). Default {@link COMMAND_KEEPALIVE_MS}. */
     commandKeepAliveMs?: number;
-    /** Power tier per station serial — injected by the facade (no model import). Default: everything `wired`. */
+    /**
+     * Power tier per station serial — injected by the facade (no model import). Default: everything
+     * `wired`. Asked about the STATION a session connects to, never the key it is filed under, so every
+     * session to one station gets that station's idle window.
+     */
     poweredFor?: (parentSn: string) => PowerTier;
     /**
-     * Called after the manager closes a station on its OWN initiative — an elapsed idle window, or a
-     * deferred reset falling due.
+     * Called with the KEY of a session the manager closed on its OWN initiative — an elapsed idle window,
+     * or a deferred reset falling due. The key, not the station: several sessions can share a station and
+     * only the one that closed is stale, so an owner told the station would tear down connections that are
+     * still serving.
      *
      * Those two are the only closes with no caller to follow up: everything riding the session is stale the
      * moment it goes, and only the owner knows what that is. A close a caller asked for is that caller's to
      * clean up after, which is why this does not fire for {@link SessionManager.close},
      * {@link SessionManager.closeAll}, or a superseded open.
      */
-    onAutoClose?: (parentSn: string) => void;
+    onAutoClose?: (key: string) => void;
     /** Diagnostics sink for the lifecycle transitions (open / idle-arm / detach). Omit for silence. */
     logger?: Logger;
 }
 /**
- * Manages P2P sessions keyed by **parent station serial**. The router builds/wires the actual
- * `P2PSession` (it owns the socket + event fan-out); this decides open/close timing.
+ * Manages P2P sessions by **key**, each recording the station it connects to. The router builds and
+ * wires the actual `P2PSession` (it owns the socket and event fan-out); this decides open/close timing.
+ *
+ * A key is the station's serial for the one session that carries its control traffic and its events.
+ * Where a station has to serve more than one camera at once it also holds a session per camera, filed
+ * under a key of the router's choosing and recording the same station — so each has its own refcount and
+ * its own idle window, and releasing one never disturbs another.
  */
 export declare class SessionManager {
     private readonly opts;
@@ -53,23 +64,40 @@ export declare class SessionManager {
     private readonly logger;
     constructor(opts?: SessionManagerOpts);
     /** The live session for a station, or `undefined` if not open. */
-    get(parentSn: string): P2PSession | undefined;
-    /** Serials of stations with a live session. */
+    get(key: string): P2PSession | undefined;
+    /** Keys of the open sessions. */
     keys(): string[];
-    /** A plain `Map<parentSn, P2PSession>` snapshot of the live sessions (for `getSessions()` / tests). */
+    /** A plain `Map<key, P2PSession>` snapshot of the open sessions (for `getSessions()` / tests). */
     liveSessions(): Map<string, P2PSession>;
-    /** Get or create the lifecycle entry for a station. */
+    /**
+     * Get or create the lifecycle entry under `key`, recording which station it connects to. An existing
+     * entry keeps the station it was opened with — the key owns one connection for its lifetime, and a
+     * later caller passing a different station would otherwise re-point a live entry's power tier.
+     */
     private entry;
-    /** Register an already-built session for test seeding or an externally assembled connection. */
-    register(parentSn: string, session: P2PSession): void;
     /**
-     * Ensure a session to `parentSn` is open, building it via `factory` if cold. Concurrent calls for the
+     * Register an already-built session for test seeding or an externally assembled connection.
+     *
+     * `station` defaults to the key, which is safe HERE and nowhere else in this class: the paths that open a
+     * session under a key that is not a station serial all go through {@link acquire}, which requires it. A
+     * caller seeding one under such a key must pass it.
+     */
+    register(key: string, session: P2PSession, station?: string): void;
+    /**
+     * Ensure a session to `key` is open, building it via `factory` if cold. Concurrent calls for the
      * same cold station share ONE connect (the `connecting` promise); `factory` builds + wires + awaits
      * `connect()` and resolves the connected session.
      */
-    acquire(parentSn: string, factory: (register: (session: P2PSession) => void) => Promise<P2PSession>): Promise<P2PSession>;
-    /** Add a reason to stay connected; cancels a pending idle-close. */
-    retain(parentSn: string): void;
+    acquire(key: string, factory: (register: (session: P2PSession) => void) => Promise<P2PSession>, station: string): Promise<P2PSession>;
+    /**
+     * Add a reason to stay connected; cancels a pending idle-close.
+     *
+     * Refused when nothing is open under `key`, for the reason {@link release} gives in the other direction: a
+     * retain names a session that was acquired, and one that names nothing would file an entry with no
+     * connection behind it. {@link hold} is the path that legitimately creates one, and it opens the entry
+     * itself before retaining it.
+     */
+    retain(key: string): void;
     /**
      * Release a reason; arm the idle-close when the last one goes.
      *
@@ -78,22 +106,28 @@ export declare class SessionManager {
      * from scratch or complete a deferred reset a real viewer has not yet earned. Clamping to zero did
      * both silently.
      */
-    release(parentSn: string): void;
+    release(key: string): void;
     /**
      * Hold a session warm for `commandKeepAliveMs` after a control command, then release. A burst of
      * commands each re-holds before the previous release fires, so the session never idles mid-burst.
      */
-    bumpCommand(parentSn: string): void;
+    bumpCommand(key: string, station: string): void;
     /**
-     * Retain a station and release it again after `ms` — the primitive behind command-keepalive and event
+     * Retain a session and release it again after `ms` — the primitive behind command-keepalive and event
      * pre-warm, and the only way to hold one open without an attachment to release it.
      *
+     * `station` is required rather than defaulted from the key, because this is the one path that can
+     * CREATE an entry: a pre-warm takes its hold before the open. An entry filed under a media key with
+     * that key as its own station would be asked for the power tier of a serial that does not exist, be
+     * answered `wired`, and never idle-detach — which on a battery station is the drain this class exists
+     * to prevent, and is invisible until the battery is flat.
+     *
      * The timer is owned by the entry, so {@link discard} cancels it. That ownership is the point: keyed
      * only by serial, an expiring hold would otherwise outlive the entry it was taken on and release a
      * retain counted by the SUCCESSOR entry — dropping a live viewer's count and arming an idle-detach
      * underneath it.
      */
-    hold(parentSn: string, ms: number): void;
+    hold(key: string, ms: number, station: string): void;
     /**
      * Arm the idle-close timer for a station whose retain count just reached zero. A wired station with
      * an infinite window is left persistent (no timer). Any subsequent {@link retain} cancels it.
@@ -123,9 +157,9 @@ export declare class SessionManager {
      */
     private autoClose;
     /** Drop a station's entry + timer (called from the session's `close` handler). Idempotent. */
-    remove(parentSn: string): void;
+    remove(key: string): void;
     /** Close one station now and discard its lifecycle entry. */
-    close(parentSn: string): Promise<void>;
+    close(key: string): Promise<void>;
     /**
      * Reset once every viewer detaches, ignoring only expiring holds.
      *
@@ -136,7 +170,7 @@ export declare class SessionManager {
      * Both branches close through {@link autoClose}: the caller asked for a recycle, not for the station's
      * live sources to be dropped, so it does not clean up after one — exactly like the idle path.
      */
-    resetWhenUnused(parentSn: string): Promise<void>;
+    resetWhenUnused(key: string): Promise<void>;
     /** Settle a discarded entry's reset callers with the same outcome as its session close. */
     private settleReset;
     /** Close one discarded entry and settle only its own reset callers before preserving any failure. */

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

@@ -10,7 +10,7 @@ export interface SharedLiveSourceOptions {
      * `.start()` itself.
      *
      * `ctx.reassertWanted` answers whether this pull still has anyone attached. A stream that re-asserts a
-     * channel to hold it open should consult it, so a pull nothing is watching stops competing for a station
+     * channel to hold it open should consult it, so a pull nothing is watching stops competing for a session
      * that serves one camera at a time.
      */
     makeStream: (ctx: {
@@ -73,6 +73,15 @@ export interface SharedLiveSourceOptions {
      * an owner does in response to this callback.
      */
     onStartFailed?: () => void;
+    /**
+     * The pull has ended and will not resume: the linger elapsed, the battery budget ran out, or the source
+     * was torn down. A later attach builds a fresh stream rather than reviving this one.
+     *
+     * Distinct from {@link onIdle} by what is still running. `onIdle` fires at the last detach, while the
+     * linger is still holding the pull open so a quick re-attach costs nothing; between the two the pull is
+     * alive. This fires when it is not.
+     */
+    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.

package/dist/transport/stored-image-cache.d.ts

@@ -10,7 +10,13 @@ export declare class StoredImageCache {
     private activeDownloads;
     private generation;
     constructor(downloader: (url: string, deviceKey: string) => Promise<Buffer>, logger: Logger, clock?: () => number, isLifecycleError?: (error: unknown) => boolean);
-    /** Observe a normalized thumbnail URL and start acquisition eagerly. */
+    /**
+     * Observe a normalized thumbnail URL and start acquisition eagerly.
+     *
+     * A URL already inside this device's window of recent attempts is ignored, so one event arriving as
+     * several pushes downloads one thumbnail. The window is a `Set`, which iterates in insertion order,
+     * so the entry evicted once it is full is the oldest attempt.
+     */
     observe(deviceKey: string, url: string): void;
     /** Return retained bytes without starting or awaiting network work. */
     snapshotStored(deviceKey: string): Promise<Buffer>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mega-yfue/eufy-sdk",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.0-beta.21",
   "description": "One typed TypeScript client for the Anker eufy v6 cloud — capability-driven devices, realtime events over P2P/MQTT/push, and live media",
   "license": "Apache-2.0",
   "author": "mega-yfue",
@@ -64,7 +64,8 @@
     "guard:docrefs": "bash scripts/ci/guard-doc-refs.sh",
     "guard:lines": "bash scripts/ci/guard-lines.sh",
     "check:esm": "node -e \"import('./dist/index.js').then(m=>console.log('ESM OK:',Object.keys(m).length,'exports'))\"",
-    "verify": "npm run format:check && npm run typecheck && npm run guard:decorrelation && npm run guard:lines && npm run guard:docrefs && npm run guard:consumer-agnostic && npm run guard:capability-ownership && npm run build && npm run check:esm && npm run typecheck:examples && npm test",
+    "check:snippets": "node scripts/ci/check-doc-snippets.mjs",
+    "verify": "npm run format:check && npm run typecheck && npm run guard:decorrelation && npm run guard:lines && npm run guard:docrefs && npm run guard:consumer-agnostic && npm run guard:capability-ownership && npm run build && npm run check:esm && npm run check:snippets && npm run typecheck:examples && npm test",
     "release": "bash scripts/release.sh"
   },
   "engines": {