@mega-yfue/eufy-sdk 0.2.0-beta.3 → 0.2.0-beta.30

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,6 +63,20 @@ 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.
  *
@@ -150,17 +164,30 @@ export type LiveTrace =
 /**
  * A station was resolved for a call, stating what the caller's device is on it and whose station it is.
  *
- * Emitted before anything is sent, so it is the only account of the intended topology on a call that fails
- * during resolution: 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.
+ * 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;
+}
+/**
+ * The call's device has no usable channel on the station it resolved: its record states none (`missing`), or
+ * another device attached to the same station states the same one (`shared`). The call is refused with
+ * `DeviceChannelUnresolvedError` and nothing is sent.
+ */
+ | {
+    phase: "station-channel-unresolved";
+    issue: "missing" | "shared";
 }
 /** A shared source began warming, with the interval it re-issues on and the deadline it fails at. */
  | {
@@ -188,6 +215,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.

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/p2p/station-channels.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Station topology and per-station channel addressing, from the device records alone.
+ *
+ * Both sides of the P2P wire key on a device's channel within its station: a media start and every
+ * per-channel command address it, and an inbound frame is attributed to the device on its channel. Resolving
+ * it once, here, keeps the two sides from ever disagreeing about which device a channel means.
+ *
+ * @module transport/p2p/station-channels
+ * @internal
+ */
+import type { EufyDevice } from "../../core/types.js";
+/**
+ * The station a device's traffic belongs to, from its cloud record and its own serial.
+ *
+ * `parent_sn` carries the parent on a HomeBase-attached device. `station_sn` is frequently absent there —
+ * empty on every attached sensor of a T8010 — and serves only as a fallback. An empty string states no
+ * station.
+ *
+ * A device naming no parent answers its own serial, so every device has a station.
+ */
+export declare function resolvedStationSn(raw: Record<string, unknown>, sn: string): string;
+/**
+ * The parent station a device's traffic belongs to — the session key the router opens and the station the
+ * frame resolver attributes by.
+ *
+ * `parent_sn` on the cloud record is the field that is actually populated for a HomeBase-attached device, so
+ * it wins; `stationSn` is frequently absent (observed empty on every attached sensor of a T8010), so keying on
+ * it alone silently resolves an attached device to ITSELF and no frame ever matches. Answering the device's
+ * OWN serial is what "stands alone" means.
+ */
+export declare function stationOf(dev: EufyDevice): string;
+/**
+ * A device's channel within its station, or why it has none. `shared` keeps the channel it `claimed`, so a
+ * frame arriving on it is known to belong to one of the claimants rather than to the station.
+ */
+export type StationChannel = {
+    channel: number;
+} | {
+    issue: "missing";
+} | {
+    issue: "shared";
+    claimed: number;
+};
+/**
+ * The channel each device is addressed by within its station.
+ *
+ * A standalone device is its own station, addressed by the channel its record states, or 0. An attached
+ * device has a channel only when its record states one that no other device attached to the same station
+ * also states. A missing channel names no device, and a channel two attached devices both state cannot say
+ * which of them it means, so either resolves to an issue rather than to a channel: guessing would address
+ * another device, streaming its video or attributing its frames under this serial. Every attached device
+ * counts towards a clash, whatever its kind, and the answer does not depend on list order.
+ */
+export declare function stationChannels(devices: readonly EufyDevice[]): Map<string, StationChannel>;

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.3",
+  "version": "0.2.0-beta.30",
   "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": {
@@ -72,14 +73,14 @@
   },
   "dependencies": {
     "jpeg-js": "^0.4.4",
-    "mqtt": "^5.15.2",
+    "mqtt": "^5.16.0",
     "protobufjs": "^8.8.0"
   },
   "devDependencies": {
-    "@types/node": "^26.5.0",
+    "@types/node": "^26.6.2",
     "esbuild": "^0.28.2",
-    "prettier": "^3.9.6",
+    "prettier": "^3.9.9",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.1"
   }
 }