@mega-yfue/eufy-sdk 0.2.0-beta.10 → 0.2.0-beta.12

package/dist/model/capabilities/battery.d.ts

@@ -90,8 +90,33 @@ export type BatteryActions = Surface<typeof BATTERY_MEMBERS>;
  * The richer raw `APP_CMD_SET_POWER_SOURCE` blob is a separate param, surfaced as `powerSourceInfo`.
  */
 declare function decodePowerSource(raw: string | number | boolean): number | string;
-/** False for a mains camera that only reports 1101 as a sentinel — used to gate the physical reads. */
-declare const notMainsCamera: (ctx: AvailabilityContext) => boolean;
+/**
+ * The params whose subject IS the physical cell — so every member reading one must carry
+ * {@link notMainsCamera}.
+ *
+ * The ONE place that fact is declared. {@link cellGated} applies {@link notMainsCamera} from this list
+ * when the table is built, so a member never states the gate itself: adding a cell read is adding its
+ * param here, and there is no second place for it to be missing from. A per-member `available` was the
+ * alternative and is what the first two passes of this guard got wrong, in both directions — first by
+ * covering two of the seven, then by reading `unexposed` as covering a third.
+ *
+ * What is NOT here matters as much.
+ *
+ *  - `workingMode` and the three `record*` settings describe how hard the camera works, not what powers
+ *    it, and a mains camera genuinely has them. They are the reason the capability stays attached.
+ *  - `cameraInfo` (1103) is a number whose meaning is unevidenced. Gating it would assert it is a
+ *    battery fact, which is the kind of claim this guard exists to stop making.
+ *  - `powerSource` (1293) is the open one. Both values it names — `Battery` and `External Solar Panel` —
+ *    describe how a CELL is fed, so by this list's own rule it arguably belongs here. It is out because
+ *    every param above is one a live mains camera was observed to publish and 1293 was not among them,
+ *    and because it is `requires`-gated on its own param, so it appears only where the device reports
+ *    it. Gating it would also withhold a described WRITE rather than a read, which is a different class
+ *    of change. Unresolved rather than decided: see the note in the pull request.
+ *
+ * The two solar params ARE here: a panel exists to charge a cell, so a device without one has no solar
+ * harvest to report either.
+ */
+export declare const CELL_PARAMS: readonly number[];
 /**
  * Every `battery` feature, declared once — the property schema, the evidence-gated getters, the derived
  * setters, the intent routes and the descriptions all come out of this table. Order is schema order.
@@ -117,7 +142,6 @@ export declare const BATTERY_MEMBERS: {
         readonly unit: "%";
         readonly kind: "percent";
         readonly provenance: "verified";
-        readonly available: typeof notMainsCamera;
         readonly description: "Battery level 0-100 (verified: param 1101).";
     };
     /**
@@ -130,7 +154,6 @@ export declare const BATTERY_MEMBERS: {
         readonly type: "bool";
         readonly kind: "boolean";
         readonly provenance: "apk";
-        readonly available: typeof notMainsCamera;
         readonly coerce: (v: string | number | boolean) => boolean;
         readonly description: string;
     };
@@ -300,6 +323,11 @@ export declare const BATTERY_MEMBERS: {
      * Reported, so it stays in the schema and answers through `getProperty` — but given no typed getter:
      * the payload's fields have never been decoded, and a getter would hand back an opaque blob typed as
      * though it meant something.
+     *
+     * `unexposed` is NOT a substitute for the cell gate. It suppresses the fluent GETTER; `propertiesOf`
+     * filters `writeOnly` and `available` and deliberately not `unexposed`, because a schema entry
+     * reachable through `getProperty` is the whole point of the mark. So a cell param needs
+     * {@link CELL_PARAMS} either way, or a mains camera publishes "battery power history" and answers it.
      */
     readonly batteryPowerStats: {
         readonly param: 3100;

package/dist/model/capabilities/index.d.ts

@@ -54,6 +54,15 @@ export declare function getCapabilityModule(cap: Capability): CapabilityModule |
  * @internal
  */
 export declare const CAPABILITY_MODULES: Record<Capability, CapabilityModule>;
+/**
+ * Every param these capabilities declare before any gate — the set a device's schema is a subset of.
+ *
+ * A param in here that a device's schema does NOT carry is one a gate withheld: the capability resolved,
+ * and its member decided the read does not describe this device — a cell reading on a mains model, a mode
+ * a family does not carry. Read-aliases count, since a member reads them under its own name.
+ * @internal
+ */
+export declare function claimedParams(caps: Capability[]): Set<number>;
 /**
  * Merge the property schemas of several capabilities into one flat, de-duplicated list.
  *

package/dist/model/device.d.ts

@@ -62,6 +62,11 @@ export declare class Device {
      * different wire ids across device families still resolves to one named value.
      */
     private specByParam;
+    /**
+     * Params a resolved capability declares that this device's schema does not carry — withheld by a
+     * member's gate, so not named from the param dictionary either. See {@link Device.applyParams}.
+     */
+    private withheld;
     /** Which param namespace this device's ids live in (clean DPs vs security P2P). */
     private namespace;
     /** The record's `device_name` as stated, before the {@link modelName} fallback is applied. */
@@ -201,6 +206,16 @@ export declare class Device {
      * Apply a raw param map (cloud record or P2P notification). Known params update their named
      * property; unrecognised params are retained as `unknown_<paramType>` so nothing is lost.
      *
+     * Naming precedence: this device's own `PropertySpec` (curated), then the param dictionary for its
+     * namespace, then the `unknown_<paramType>` passthrough. The dictionary def is consulted even where a
+     * spec exists, because `encoding` lives there.
+     *
+     * A param a resolved capability's gate WITHHELD takes the passthrough instead of its dictionary name.
+     * The gate decided the read does not describe this device, the dictionary names it what the member
+     * would have, and republishing it there hands a caller a reading indistinguishable from one the device
+     * really answered. A capability that never resolved withholds nothing: a param arriving before its
+     * capability is still the device's own, and keeps its dictionary name.
+     *
      * @param params param_type → raw value.
      * @param ts observation time (epoch ms); defaults to `Date.now()`.
      * @returns the list of property names whose value changed.

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

@@ -88,7 +88,7 @@ export interface P2PRouterDeps {
 }
 export declare class P2PCommandRouter {
     private readonly deps;
-    /** Per-station P2P session lifecycle: on-demand open + battery-aware idle-detach + refcount. */
+    /** P2P session lifecycle: on-demand open + battery-aware idle-detach + refcount, per session key. */
     private readonly manager;
     /** Error objects already forwarded while a station startup awaits the same session signal. */
     private readonly reportedErrors;
@@ -96,6 +96,21 @@ export declare class P2PCommandRouter {
     private readonly liveSources;
     /** The options each live source was built from, so a later caller's conflicting ones can be reported. */
     private readonly liveSourceOpts;
+    /**
+     * The session each live source pulls over — the station's own serial, or the source's own media
+     * session key.
+     *
+     * Written the instant the choice is made and BEFORE the connection is opened, which is what makes it
+     * a reservation rather than a record. Two cameras started together (the four-tile case this feature
+     * exists for) would otherwise both find the station's session free: a consumer attaches only after
+     * `sharedLiveSourceFor` returns, so neither is visible to the other through consumer counts, and both
+     * would take the shared connection and contend on it.
+     *
+     * A station entry is kept as well as a media one, because "is the station's own session already
+     * claimed" is the question being asked, and an entry that is present but not yet in
+     * {@link liveSources} is a claim in flight.
+     */
+    private readonly liveSessionKeys;
     /**
      * The open talkback per `${parentSn}:${channel}`, if any. The device plays one audio stream at a
      * time and the session carries one audio sequence, so this path is exclusive where a live pull is
@@ -122,7 +137,10 @@ export declare class P2PCommandRouter {
      * `no P2P session`.
      */
     static claimsDevice(dev: EufyDevice): boolean;
-    /** Stations with a live P2P session (a snapshot; mutate via the lifecycle methods, not this map). */
+    /**
+     * The open P2P sessions by key — a station's own under its serial, a camera's media session under
+     * `<stationSn>#live:<channel>` (a snapshot; mutate via the lifecycle methods, not this map).
+     */
     getSessions(): Map<string, P2PSession>;
     /**
      * Speculatively open + briefly hold a station's session (e.g. after a doorbell ring) so a
@@ -132,7 +150,7 @@ export declare class P2PCommandRouter {
      *
      * One hold, taken before the open so a slow connect can't idle-close mid-flight. It expires on its
      * own, which arms the station's idle window rather than closing the session, per {@link PREWARM_MS}.
-     * A second hold after the open would buy nothing: {@link openStation} returns once the socket is bound
+     * A second hold after the open would buy nothing: {@link openSession} returns once the socket is bound
      * and the lookups are away, not once the peer has answered, so both would expire together.
      *
      * Best-effort — a failed open surfaces via `onError`. A {@link SessionSupersededError} does not: the
@@ -165,7 +183,41 @@ export declare class P2PCommandRouter {
      * when present, else the freshest private IP in the record ({@link freshestLanIp}) — so P2P works
      * on-LAN even when broadcast is blocked (AP isolation) or the record's `ip_addr` went stale.
      */
-    private openStation;
+    /**
+     * The key a camera's own media session is filed under, distinct from every station serial because a
+     * serial contains no `#`.
+     */
+    private static mediaSessionKey;
+    /** Whether `key` names a media session rather than a station's own. */
+    private static isMediaSessionKey;
+    /**
+     * Open (or reuse) a SECOND connection to a station, carrying one camera's media and nothing else.
+     *
+     * One session serves one camera: a station fans its cameras over a session and answers the most recent
+     * start on it, so two cameras down one tunnel take it from each other in turn. Another connection is
+     * how a station serves another camera.
+     *
+     * The hardware was shown to do this before the SDK did. A first-party display showing four tiles was
+     * captured opening one PPCS session per camera, with three cameras' video arriving in the same second
+     * at 2304x1296, 1600x1200 and 3840x2160 — three geometries at once, which no composed stream can be.
+     * Reproduced here afterwards on a base carrying two attached cameras, one at 3840x2160, both holding
+     * full frame rate at once over a session each, where the same pair down one session could only take
+     * turns.
+     *
+     * It carries media alone. The station announces its state to every client that connects, so a session
+     * wired to the same fan-out would report every event a second time; {@link makeSession} leaves this one
+     * unannounced, and the station's own session stays the single source of connection state, control
+     * notifications and frames.
+     *
+     * The level-2 key is waited for here on the same terms the station's own session gets, because a
+     * connection is not usable for this without one: an attached camera's media start has no level-1 form,
+     * so a start issued before the key arrives is dropped as `media-command-unsent`, and the stream then
+     * shows nothing until a later keepalive tick happens to find the key. A connected session that cannot
+     * carry the start is not a connected session, so this refuses rather than returning one.
+     */
+    private openMediaSession;
+    /** Open (or reuse) the session filed under `key`, dialling `parentSn`'s endpoint. */
+    private openSession;
     /**
      * Build + wire a {@link P2PSession} for a station (NOT yet connected — the caller awaits `connect()`).
      *
@@ -177,6 +229,12 @@ export declare class P2PCommandRouter {
      *
      * The `close` handler drops the session from the {@link SessionManager} and disposes any shared live
      * source riding this station (consumers get `stop`; a later attach rebuilds via the factory).
+     *
+     * A session filed under a media key is wired for errors and its own teardown ONLY. Connection state,
+     * level-2 readiness and inbound frames all reach the owner through the station's own session, and a
+     * station announces those to every client that connects — so fanning a second connection's copies out
+     * under the same station serial would report each one twice, and a close would tear down the station
+     * while its own session is still serving.
      */
     private makeSession;
     /**
@@ -285,22 +343,40 @@ export declare class P2PCommandRouter {
      * {@link releaseLingeringSiblings}. A pull with consumers is never touched. The release runs before the
      * reuse branch, so a reuse frees the station as a cold start does.
      *
+     * `mayOpenOwnSession` decides whether a camera that finds the station's own session claimed may open a
+     * connection of its own for it. Only the continuous-pull egresses pass it. A still must not: it wants one
+     * frame, and a socket plus a level-2 negotiation per thumbnail is a cost a tile refresh cannot justify —
+     * so a still asked for while a sibling is being watched contends as it always did, and the caller's
+     * retained image answers it. A live view still outranks a tile; what changed is that two live views no
+     * longer have to outrank each other.
+     *
      * The session goes into a {@link HeldSession} cell, so it can be replaced under a source that stays in
      * place.
      */
-    sharedLiveSourceFor(sn: string, opts?: SharedLiveOpts): Promise<SharedLiveSource>;
+    sharedLiveSourceFor(sn: string, opts?: SharedLiveOpts, mayOpenOwnSession?: boolean): Promise<SharedLiveSource>;
     /**
      * Tear down any pull on this station that is lingering for ANOTHER camera, before starting this one.
      *
      * A lingering pull has no consumers but is still held open, and on an attached camera holding it open means
-     * re-sending the full media start every keepalive tick. Two channels doing that at once on a station that
-     * serves one camera at a time leaves the new stream receiving nothing but the old camera's frames for as
-     * long as the linger lasts.
+     * re-sending the full media start every keepalive tick. Two channels doing that at once over ONE session,
+     * which serves one camera at a time, leaves the new stream receiving nothing but the old camera's frames
+     * for as long as the linger lasts.
      *
      * Several cameras genuinely being WATCHED together are never disturbed — the linger exists to make
      * re-opening the SAME camera cheap, and it keeps doing that. What it may not do is keep a camera nobody is
      * looking at competing with one somebody just asked for.
      *
+     * An `idle` source is skipped, because it is not a linger and holds nothing: it has never warmed, so it
+     * has sent no media start and is competing for nothing. Without that, two cameras opened at the same
+     * moment destroy each other — the second finds the first's source built but not yet attached to, reads
+     * zero consumers as a linger, and disposes the source its caller is holding. Which is the four-tile case
+     * this whole path exists for.
+     *
+     * A sibling lingering on a connection of its OWN is skipped for the same reason stated the other way: the
+     * contention this releases is contention over one session, and that sibling is not on this one. Dropping
+     * it would close a socket and throw away the cheap re-attach the linger exists to provide, to relieve a
+     * competition that is not happening.
+     *
      * A snapshot tile is nobody looking. Opening a live view in the Home app takes that cell fullscreen, so the
      * pulls refreshing the other cells are off screen, yet each goes on re-issuing its own media start every
      * retry tick — measured as four pulls warming together off one HomeBase, a live request landing 1.4 s later,
@@ -311,14 +387,27 @@ export declare class P2PCommandRouter {
      */
     private releaseLingeringSiblings;
     /**
-     * The channel a live viewer already holds on this station, if any, ignoring `key` itself.
+     * Whether another camera has already claimed this station's OWN session, ignoring `key`.
+     *
+     * The question a newcomer has to answer is not whether the station is busy — it can serve one camera
+     * per connection — but whether the connection it would otherwise share is taken. A camera on a media
+     * session of its own does not hold this one, so a station whose first camera has since stopped hands
+     * its own session to the next arrival rather than opening a socket beside an idle one.
+     *
+     * A claim counts while its source is still `idle`, source or no source. That is a start that has been
+     * handed to its caller but not yet attached to, and it is the only state in which two cameras asked for
+     * at the same moment can see each other: consumers attach after this method has already run for both.
+     *
+     * The cost is that a pull genuinely abandoned before its first attach goes on holding the station's own
+     * session, and the next camera pays for a connection of its own rather than reclaiming it. That is one
+     * socket against destroying a start someone is waiting on, which is not a close trade.
      *
      * A stopped source is skipped even when consumers are still attached to it. A failed start fails its
      * consumers without detaching them, so a caller still holding a dead handle leaves the count non-zero,
-     * and counting that as a viewer would refuse every later stream on the station until the client
-     * restarted. Only a source that can still deliver holds a place.
+     * and counting that as a viewer would put every later camera on a connection of its own until the
+     * client restarted. Only a source that can still deliver holds a place.
      */
-    private occupiedSiblingChannel;
+    private stationSessionInUse;
     /**
      * Whether the stream on `key` should re-assert its channel to hold the station.
      *
@@ -328,8 +417,8 @@ export declare class P2PCommandRouter {
      *  - Nothing attached: no. There is nobody to take the station for.
      *  - A live viewer attached: yes. That is the picture someone is looking at.
      *  - Held only for stills, while a sibling on this station has a live viewer: no. A still refreshes a
-     *    tile that is off screen while the live view is on it, and a station serving one camera at a time
-     *    cannot satisfy both. Measured: a still on a sibling halved a live view's frame rate for as long as
+     *    tile that is off screen while the live view is on it, and one session serving one camera at a time
+     *    cannot satisfy both — and a still does not open a connection of its own. Measured: a still on a sibling halved a live view's frame rate for as long as
      *    it took, and its own capture then took fifteen seconds because it was contending.
      *
      * A still with no live sibling re-asserts, so a tile refreshing on a quiet station is
@@ -344,8 +433,24 @@ export declare class P2PCommandRouter {
      * not.
      */
     private attachUnlessAborted;
-    /** Dispose one cached live source and forget it, so the next acquisition builds a fresh one. */
+    /**
+     * 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
+     * can reach that connection, so leaving it open would hold a socket and a station keepalive for a
+     * camera no longer being pulled. A claim on the STATION's own session is released without closing
+     * anything — that connection carries the station's control traffic and outlives any one camera.
+     */
     private dropLiveSource;
+    /** Close and forget the media session `key`'s live source owned, if it owned one. */
+    private closeMediaSession;
+    /**
+     * Drop the live source a media session was carrying, after that session closed on its own.
+     *
+     * The source holds the closed connection and never re-resolves it, so it can only answer its retained
+     * keyframe and then fail on its warm-up deadline. Its consumers get `stop`, and the next attach builds
+     * a fresh source — which, finding the station busy again, opens a fresh media session for it.
+     */
+    private tearDownMediaSession;
     /**
      * Drop everything that was riding a station's session, and report the station closed.
      *

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/media.d.ts

@@ -36,8 +36,8 @@ export declare function openLiveStream(session: P2PSession, opts?: LiveStreamOpt
  * 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. A station serves one camera at a time and the SDK refuses a
- * second channel on one that is busy, so a still that kept its pull attached across its own decode would deny
+ * 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.
  *

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mega-yfue/eufy-sdk",
-  "version": "0.2.0-beta.10",
+  "version": "0.2.0-beta.12",
   "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",