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

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

@@ -18,6 +18,23 @@ import type { FfmpegLevel } from "../ffmpeg.js";
 import { SharedLiveSource } from "./shared-live-source.js";
 import { type PowerTier, type SessionManagerOpts } from "./session-manager.js";
 import { FragmentRecording } from "./fragment-recording.js";
+/**
+ * What a caller's own deadline on a station call has to clear, in milliseconds.
+ *
+ * A caller that bounds one of these calls itself races these waits, and a bound below them reports the
+ * caller's own expiry in place of the reason this SDK was about to give — the two are indistinguishable to
+ * whoever reads the outcome, and they call for different next steps. Published so that bound can be derived
+ * rather than copied: a literal in a caller's source is a second source of truth that goes stale silently
+ * when these change.
+ *
+ * `connect` applies to every call on a station, because nothing can be addressed to one before its session is
+ * up. `level2Grace` applies twice where the key is required: the negotiation is re-prompted once.
+ */
+export declare const P2P_STATION_WAITS: {
+    readonly connect: 20000;
+    readonly level2Grace: 25000;
+    readonly level2Settle: 8000;
+};
 /**
  * Options accepted when warming a {@link SharedLiveSource} for a device (all optional).
  *
@@ -90,6 +107,12 @@ export declare class P2PCommandRouter {
     constructor(deps: P2PRouterDeps);
     /** Forward one P2P failure once even when both the session listener and startup waiter observe it. */
     private reportError;
+    /**
+     * Emit a live trace under a station session's handle, for work this router does ON that session before
+     * the session itself records anything — reaching the station, and resolving what a device is on it. Same
+     * handle as everything the session goes on to trace, which is what groups one attempt.
+     */
+    private traceOnStation;
     /**
      * Whether this transport stack drives `dev`'s `ff09-*` commands — true when the device has its own
      * usable P2P endpoint (a non-empty `p2p_did`). The command sink asks each stack this to route a

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

@@ -10,4 +10,5 @@ export * from "./envelope.js";
 export * from "./write-commands.js";
 export * from "./lan-ip.js";
 export { LIVE_TRACE_MESSAGE, type LiveTrace } from "./live-trace.js";
+export { P2P_STATION_WAITS } from "./command-router.js";
 export * as p2pCodec from "./codec.js";

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

@@ -63,12 +63,37 @@ export type LiveTrace =
     phase: "sequence-restart";
     dataType: number;
 }
+/**
+ * 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 +104,63 @@ 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 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.
+ */
+ | {
+    phase: "station-resolved";
+    topology: "attached" | "own";
+    channel: number;
+    stationAdmin: "self" | "other" | "unstated";
 }
 /** A shared source began warming, with the interval it re-issues on and the deadline it fails at. */
  | {
@@ -110,6 +188,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. 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
+ * 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

@@ -208,6 +208,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/package.json

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