@mega-yfue/eufy-sdk 0.5.0-beta.25 → 0.5.0-beta.27

package/dist/transport/abortable.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Settle `work` as it settles, or reject the moment `signal` aborts, whichever comes first.
+ *
+ * The underlying wait is left to finish on its own: it may be shared work other callers are waiting on, so a
+ * caller abandoning its own call does not cancel the work itself. This abandons WAITING, which is the only
+ * part that belonged to the caller.
+ */
+export declare function abortable<T>(work: Promise<T>, signal?: AbortSignal): Promise<T>;

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

@@ -1,14 +1,3 @@
-/**
- * P2P command router — the transport-side owner of the ThroughTek PPCS sessions and every wire
- * operation over them: opening sessions, resolving a serial to its session + routing params,
- * mapping a transport-neutral {@link Command} to a concrete frame (encryption level, wire shape),
- * the fire-and-forget control senders, request/reply queries, and the media provider.
- *
- * Layering: this module knows P2P bytes; it does NOT know capabilities. Frame → semantic-event
- * decoding is a model concern, so raw frames are handed back to the client via {@link P2PRouterDeps.onFrame}
- * (the client gates them on device capabilities and emits typed events). This keeps transport free of
- * any `model/` import — the capability↔transport decorrelation invariant.
- */
 import type { MegaHttpClient } from "../http/mega-client.js";
 import type { EufyDevice } from "../../core/types.js";
 import type { Command, AutoLockSnapshot, MediaProvider, SharedSourceHints, AbortableCall } from "../../core/contracts.js";
@@ -461,15 +450,6 @@ export declare class P2PCommandRouter {
      * A still with no live sibling re-asserts, so a tile refreshing on a quiet station is
      * unaffected.
      */
-    /**
-     * Attach a consumer, unless the caller has already abandoned the call.
-     *
-     * The acquisition it just waited through can outlast the caller's interest, and a consumer attached for
-     * somebody who has gone keeps the pull warm for nobody. Detaching immediately gives the pull back, which
-     * lets it linger and fall away if this was the only thing holding it, and leaves it untouched if it was
-     * not.
-     */
-    private attachUnlessAborted;
     /**
      * Dispose one cached live source and forget it, so the next acquisition builds a fresh one. Its claim
      * on a session goes with it, and a media session opened for this source alone is closed: nothing else

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

@@ -438,3 +438,12 @@ export declare class SharedLiveSource {
      */
     dispose(): void;
 }
+/**
+ * Attach a consumer, unless the caller has already abandoned the call.
+ *
+ * The acquisition it just waited through can outlast the caller's interest, and a consumer attached for
+ * somebody who has gone keeps the pull warm for nobody. Detaching immediately gives the pull back, which
+ * lets it linger and fall away if this was the only thing holding it, and leaves it untouched if it was
+ * not.
+ */
+export declare function attachUnlessAborted(source: SharedLiveSource, signal?: AbortSignal): Consumer;

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

@@ -71,6 +71,8 @@ export declare class VideoFrameDecoder {
 }
 /** One whole access unit recovered from the frame (or frames) the station sent it in. */
 export interface AssembledAccessUnit {
+    /** Unsigned 32-bit header timestamp from the first frame of this access unit. */
+    sourceTimestamp: number;
     /** True when the unit's own header flagged it a keyframe — a point a consumer may begin decoding at. */
     keyframe: boolean;
     /** Frame width the unit's header declared. */

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

@@ -10,11 +10,15 @@
  * A command to the station goes on the station channel `255`; an attached device's command shares the
  * station's session and keeps the device's channel. Other command kinds are refused.
  *
- * One session per station, reused across commands and closed after {@link IDLE_CLOSE_MS} without one.
- * Sends on a session are serialised; an ACK is correlated by its outer command and segment, since it
- * carries no inner command. An ACK is not an observation of the resulting state.
+ * One session per station, reused across commands and closed after {@link IDLE_CLOSE_MS} without one;
+ * a live pull holds it open. Sends on a session are serialised; an ACK is correlated by its outer command
+ * and segment, since it carries no inner command. An ACK is not an observation of the resulting state.
+ *
+ * Live view of an attached camera rides the same session (the hub accepts one RTC session per account),
+ * through one shared live source per station: the station serves one camera at a time, so a second
+ * camera is refused until the first one's view ends.
  */
-import type { Command } from "../../core/contracts.js";
+import { type Command, type MediaProvider } from "../../core/contracts.js";
 import type { Logger } from "../../core/logger.js";
 import { RtcSession, type RtcSessionOptions } from "./session.js";
 export interface RtcIdentity {
@@ -38,6 +42,12 @@ export interface RtcRoute {
     /** True for a device attached to the station, which keeps the command's own channel. */
     attached: boolean;
 }
+/** The camera a live view is for, on its station's route. */
+export interface RtcLiveRoute extends RtcRoute {
+    cameraSn: string;
+    /** The camera's `device_channel` on the station. */
+    channel: number;
+}
 export interface RtcCommandRouterDeps {
     /** The logged-in session's credentials; `undefined` while logged out. */
     identity: () => RtcIdentity | undefined;
@@ -47,15 +57,39 @@ export interface RtcCommandRouterDeps {
     country?: string;
     logger?: Logger;
     onError?: (e: Error) => void;
+    /** ffmpeg for the live still (`ffmpeg` on PATH by default). */
+    ffmpegPath?: string;
     createSession?: (opts: RtcSessionOptions) => RtcSession;
 }
 export declare class RtcCommandRouter {
     private readonly deps;
     private readonly sessions;
+    private readonly lives;
     constructor(deps: RtcCommandRouterDeps);
     dispatchCommand(route: RtcRoute, cmd: Command): Promise<void>;
-    /** Tear down every station session (logout / shutdown). */
+    /**
+     * The media of a camera on a T9000: live video, a readable feed and a live still over the station's
+     * session. Recording has no wire here and is refused; the optional members it has no wire for are absent.
+     */
+    mediaProviderFor(route: RtcLiveRoute): MediaProvider;
+    /**
+     * Tear down every station session (logout / shutdown). Each live source is disposed before its session
+     * closes, so its consumers end cleanly and its stop still rides the session.
+     */
     close(): void;
+    /**
+     * Hand `use` the station's live source for this camera, in the same turn the source is created or reused,
+     * so a consumer it attaches is counted before any other caller looks.
+     *
+     * The station streams one camera at a time. Another camera whose source has consumers refuses this one,
+     * before the session is awaited and again after; one with none (never attached or lingering)
+     * holds nothing a viewer needs, so it is disposed and the slot taken. The first caller's
+     * {@link SharedSourceHints} configure a new source.
+     */
+    private withLiveSource;
+    /** Refuse a camera while another camera on its station has consumers. */
+    private refuseIfWatched;
+    private newLiveSource;
     /**
      * Completes on the command ACK or a correlated control-result notification. The notification must
      * match the request channel, parameter and segment and contain a structured payload. Receipt does

package/dist/transport/rtc/live.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The live pull of one camera behind a **HomeBase S1 Pro (T9000)**, over the station's control session.
+ *
+ * Wire, as the portal sends it on the command data channel:
+ *
+ *  - Start is inner `cmd 1003` in a `1350` SET_PAYLOAD on the station channel `255`. The header byte the
+ *    codec names `isResponse` carries the portal's `streamId`, `1` for a live view, and `chn_list` is an
+ *    array of `{index, chn, sensor, isUps, isClicked}` objects. Stop is inner `cmd 1004`, the same way.
+ *  - Video arrives on the live link as portal packets `1300` on channel `100 + play id`; a single-camera
+ *    view is play id `1`, whatever the camera's own channel. Each body is a fixed 22-byte media header,
+ *    then the Annex B video it declares. See {@link parseMediaBody}.
+ *  - A raw, unframed keepalive (a 20-byte prefix and a bare `XZYH 1139`) goes out every ~29 s; the hub
+ *    echoes it.
+ *
+ * The station serves one live view at a time on that play slot, so the router builds at most one pull per
+ * station. This is a {@link LiveStreamHandle}: fan-out, backpressure and the start deadline are the
+ * shared live source's.
+ */
+import { EventEmitter } from "node:events";
+import type { LiveStreamHandle } from "../../core/contracts.js";
+import type { Logger } from "../../core/logger.js";
+import type { RtcSession } from "./session.js";
+import { type SegmentCounter } from "./portal-packet.js";
+/**
+ * Read a `1300` body: a 22-byte media header (u32 LE video length at 0, stream type at 5, u16 LE width
+ * and height at 10 and 12), then the Annex B video. This is the layout the portal's own HEVC worker
+ * parses. Answers `undefined` for a short body, a stream that is not HEVC, or a declared length the body
+ * does not hold.
+ */
+export declare function parseMediaBody(body: Buffer): {
+    data: Buffer;
+    width: number;
+    height: number;
+} | undefined;
+export interface RtcLiveOptions {
+    session: RtcSession;
+    /** The session's segment counter, shared with the command router so segments never collide. */
+    seg: SegmentCounter;
+    stationSn: string;
+    /** The camera's `device_channel` on the station. */
+    channel: number;
+    /** The station's `member.admin_user_id`. */
+    accountId: string;
+    logger?: Logger;
+}
+/**
+ * One camera's live pull. `start()` sends the start; a non-zero start ACK or a closed session ends it with
+ * `error`, and `stop()` sends the stop. Frames are `h265` Annex B, keyframes being IDRs.
+ */
+export declare class RtcLiveStream extends EventEmitter implements LiveStreamHandle {
+    private readonly opts;
+    private running;
+    private startSegment;
+    private keepalive?;
+    private width;
+    private height;
+    private readonly onMedia;
+    private readonly onCommand;
+    private readonly onClose;
+    constructor(opts: RtcLiveOptions);
+    private get tag();
+    start(): this;
+    stop(): void;
+    private teardown;
+    private fail;
+    /** The start's ACK: a non-zero result code ends the pull. */
+    private onCommandFrame;
+    private onMediaFrame;
+}

package/dist/transport/rtc/peer.d.ts

@@ -77,6 +77,11 @@ export declare class RtcPeer extends EventEmitter<RtcPeerEvents> {
      */
     handleRemoteOffer(offerSdp: string): Promise<string>;
     addRemoteCandidate(candidate: string): void;
+    /**
+     * Send bytes on the command channel as they are, without PTCS framing; false when it isn't open. The
+     * portal's data-channel keepalive rides the wire unframed.
+     */
+    sendRaw(bytes: Buffer): boolean;
     /**
      * Send one portal packet on the command channel, through the framer. False when the channel is not
      * usable or the native send refused a wire packet, so a dropped frame does not read as success.

package/dist/transport/rtc/portal-packet.d.ts

@@ -10,12 +10,18 @@
  * `worker_sctp_send`.
  */
 export declare const PORTAL_HEADER_LENGTH = 16;
+/** The SET_PAYLOAD envelope. */
+export declare const PORTAL_CMD_SET_PAYLOAD = 1350;
+/** The channel a station-wide command is addressed to. */
+export declare const PORTAL_STATION_CHANNEL = 255;
 /** Portal link types — which logical channel a frame belongs to (`worker_sctp_send`). */
 export declare const PortalLinkType: {
     /** Command channel: requests out, acknowledgements back. */
     readonly COMMAND: 1;
     /** Station-originated frames: pushes, notify payloads, control results. */
     readonly NOTIFY: 3;
+    /** Live video. */
+    readonly LIVE: 5;
 };
 export interface PortalHeader {
     commandId: number;

package/dist/transport/rtc/ptcs-framer.d.ts

@@ -7,7 +7,7 @@
  *
  *   0   "PTCS"
  *   4   u8   3              constant
- *   5   u8   channel        the logical channel the frame belongs to: 0 command, 2 notify
+ *   5   u8   channel        the logical channel the frame belongs to: 0 command, 2 notify, 5 live
  *   6   u16  sequence       a frame counter: every packet of a frame carries the same value, and it
  *                           steps once per frame
  *   8   u32  frame id       one value per frame, shared by all its packets — the portal uses a ms clock
@@ -28,8 +28,9 @@ export declare const PTCS_DEFAULT_PAYLOAD_BYTES = 1000;
 export declare const PtcsChannel: {
     readonly COMMAND: 0;
     readonly NOTIFY: 2;
+    readonly LIVE: 5;
 };
-/** The link type a received frame belongs to: notify on the notify channel, command otherwise. */
+/** The link type a received frame belongs to: notify and live on their channels, command otherwise. */
 export declare function linkTypeForChannel(channel: number): number;
 /** How long a partly received frame is kept before it is dropped. */
 export declare const PTCS_STALE_MS = 15000;

package/dist/transport/rtc/session.d.ts

@@ -31,8 +31,10 @@ export interface RtcSessionEvents {
     connected: [];
     close: [];
     error: [err: Error];
-    /** A reassembled frame: portal packet bytes + the link type it arrived on. */
+    /** A reassembled command or notify frame: portal packet bytes + the link type it arrived on. */
     commandData: [frame: Buffer, linkType: number];
+    /** A reassembled live-video frame. */
+    mediaData: [frame: Buffer];
 }
 export declare class RtcSession extends EventEmitter<RtcSessionEvents> {
     private readonly opts;
@@ -57,6 +59,8 @@ export declare class RtcSession extends EventEmitter<RtcSessionEvents> {
     connect(): Promise<void>;
     /** Send one portal packet; false when the command channel isn't open. */
     sendCommand(portalPacket: Buffer): boolean;
+    /** Send unframed bytes on the command channel; false when it isn't open. */
+    sendRaw(bytes: Buffer): boolean;
     /**
      * Hang up and tear both sides down; `close` fires once, here if nothing announced it before. A
      * `connect()` still waiting for the signalling auth is rejected and its timer stopped.

package/package.json

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