@mega-yfue/eufy-sdk 0.5.0-beta.5 → 0.5.0-beta.50

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

@@ -0,0 +1,86 @@
+/**
+ * The PTCS packetiser: a clean-room implementation of the framing the portal wraps around every portal
+ * packet on `WebrtcDataChannel` (the portal's `libsctp` module). Nothing of that module ships here.
+ *
+ * Every wire packet is the same size, `28 + payload bytes`, zero-padded. The size is carried per packet,
+ * so the receiver accepts any:
+ *
+ *   0   "PTCS"
+ *   4   u8   3              constant
+ *   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
+ *   12  u32  frame length   total bytes of the frame
+ *   16  u16  packet index   0-based position of this packet in the frame
+ *   18  u16  0x4000 | (last ? 0x0400 : 0) | payload length      (payload ≤ 1023 fits the low bits)
+ *   20  8 × 0
+ *   28  payload             `payload length` bytes, then zeros to the packet size
+ *
+ * The format carries no forward error correction. The receiver completes a frame only when every index
+ * up to the `last` one is present and their lengths add up; frames whose packets stop arriving are
+ * dropped after {@link PTCS_STALE_MS}.
+ */
+export declare const PTCS_HEADER_LENGTH = 28;
+/** The portal's packet payload size: 1028-byte packets, 1000 bytes of payload after the header. */
+export declare const PTCS_DEFAULT_PAYLOAD_BYTES = 1000;
+/** SCTP channel ids as the portal numbers them, and the link type each maps to on receive. */
+export declare const PtcsChannel: {
+    readonly COMMAND: 0;
+    readonly NOTIFY: 2;
+    readonly LIVE: 5;
+};
+/** 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;
+export interface PtcsHeader {
+    channel: number;
+    /** The sender's running packet counter — see the header map. */
+    sequence: number;
+    frameId: number;
+    frameLength: number;
+    index: number;
+    last: boolean;
+    payloadLength: number;
+}
+export declare function parsePtcsHeader(packet: Buffer): PtcsHeader | undefined;
+/** Split one frame into wire packets. */
+export declare function packetize(frame: Buffer, opts: {
+    channel?: number;
+    frameId: number;
+    payloadBytes?: number;
+    sequence?: number;
+}): Buffer[];
+/** Reassemble frames from wire packets, in any order, one frame at a time per (channel, id). */
+export declare class PtcsReassembler {
+    private readonly onFrame;
+    private readonly now;
+    private readonly partials;
+    constructor(onFrame: (frame: Buffer, channel: number) => void, now?: () => number);
+    push(packet: Buffer): boolean;
+    /** Drop frames that stopped arriving; call periodically. */
+    expire(): void;
+}
+/** Frame ids the way the portal draws them — a millisecond clock, nudged forward on a collision. */
+export declare function frameIdClock(now?: () => number): () => number;
+/**
+ * The framer between portal packets and the data channel: PTCS out, PTCS in, with the portal's channel
+ * mapping. An inbound bare `XZYH` packet, which the hub sometimes answers with, passes through as a
+ * command frame. Frame ids are a millisecond clock and the frame counter starts at 0.
+ */
+export declare class PtcsFramer {
+    private onWire?;
+    private onFrame?;
+    private reassembler?;
+    private sweep?;
+    private ready;
+    private readonly nextFrameId;
+    private sequence;
+    /** Arm the two callbacks; `sendFrame` may be called from here on. */
+    init(onWirePacket: (packet: Buffer) => void, onFrame: (frame: Buffer, linkType: number) => void): void;
+    isReady(): boolean;
+    sendFrame(portalPacket: Buffer): void;
+    recvPacket(wirePacket: Buffer): void;
+    destroy(): void;
+}

package/dist/transport/rtc/scall-sdp.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The T9000's signalling does not carry SDP text: an `info` message carries a small JSON — DTLS setup
+ * role, ICE ufrag/pwd, fingerprint and candidates — and each side rebuilds the one-m-line SDP from it.
+ * This is the portal's own translation (security.eufy.com): the SDP handed to the native peer is the one
+ * the hub meant, and the JSON sent back is the one the hub parses.
+ */
+export interface ScallSdpJson {
+    setup?: string;
+    ice?: {
+        ufrag?: string;
+        pwd?: string;
+        fingerprint_type?: string;
+        fingerprint?: string;
+    };
+    candidate?: string[];
+}
+/** The hub's SDP is one SCTP application m-line bundled under mid 2, as the portal template has it. */
+export declare const HUB_SDP_MID = "2";
+/** The max message size the hub advertises; the answer carries the same. */
+export declare const ANKER_MAX_MESSAGE_SIZE = 262144;
+/**
+ * Rebuild the hub's offer (or answer) SDP from its scall JSON. The JSON carries the fingerprint as bare
+ * hex; the SDP gets colon-separated byte pairs.
+ */
+export declare function scallJsonToSdp(json: ScallSdpJson, now?: () => number): string;
+/** Reduce our local SDP to the JSON the hub parses. `actpass` is left out: the hub wants a concrete role. */
+export declare function sdpToScallJson(sdp: string): ScallSdpJson;
+/** The candidate type (`host` / `srflx` / `relay`) named inside an ICE candidate line. */
+export declare function iceCandidateType(candidate: string): string;
+/** Pin `a=max-message-size` to what the hub advertises, whatever libdatachannel wrote. */
+export declare function pinMaxMessageSize(sdp: string): string;
+/**
+ * Force a concrete DTLS role into an SDP. The hub offers `actpass`; the peer pins that offer to
+ * `passive`, which leaves one legal answer, `active`. The DTLS client opens its data channels on the
+ * even SCTP stream ids (RFC 8832), and the hub pairs with those: its command channel is stream 0.
+ */
+export declare function forceDtlsRole(sdp: string, role: "active" | "passive"): string;
+/**
+ * The wire form of a trickled ICE candidate: `candidate:...`, the attribute's value, which is the shape
+ * the hub sends and parses. The native peer hands out the SDP attribute line (`a=candidate:...`).
+ */
+export declare function toWireCandidate(candidate: string): string;

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

@@ -0,0 +1,90 @@
+/**
+ * One T9000 command session end to end: sign → signalling socket → `scall` → the hub's SDP offer →
+ * our answer → ICE → DTLS → the command data channel open.
+ *
+ * The signalling exchange, as the portal runs it and as confirmed live:
+ *
+ *   → scall                          (action 3, channel 0, the hub's own session)
+ *   ← scall {status: 100, turn}      the hub granted the session and handed out TURN credentials
+ *   ← info  {sdp | format:"SDP"}     the hub's offer, as scall JSON
+ *   → info  {sdp}                    the answer
+ *   ↔ info  {candidate}              trickle ICE on the same channel; "" ends it
+ *   ← scall {status: 200}            → ack
+ *   ← scall {status: 486 | 408}      busy / timeout: the session fails
+ *   ← hangup                         the hub ended it
+ *
+ * The command data channel is the session: `close` fires once, when the channel closes, the peer fails,
+ * the signalling socket drops or {@link RtcSession.close} is called, even while the peer connection is
+ * nominally up.
+ *
+ * Both the signalling client and the peer are injectable.
+ */
+import { EventEmitter } from "node:events";
+import { RtcPeer, type RtcPeerOptions } from "./peer.js";
+import { RtcSignalingClient, type RtcSignalingOptions } from "./signaling.js";
+export interface RtcSessionOptions extends RtcSignalingOptions {
+    peer?: RtcPeerOptions;
+    createSignaling?: (opts: RtcSignalingOptions) => RtcSignalingClient;
+    createPeer?: (opts: RtcPeerOptions) => RtcPeer;
+}
+export interface RtcSessionEvents {
+    connected: [];
+    close: [];
+    error: [err: Error];
+    /** 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];
+    /** The hub echoed the portal keepalive on the command channel. */
+    keepaliveEcho: [];
+}
+export declare class RtcSession extends EventEmitter<RtcSessionEvents> {
+    private readonly opts;
+    private readonly signaling;
+    private readonly peer;
+    private readonly logger;
+    private turn?;
+    private authOk;
+    private authWaiter?;
+    private connected;
+    private closed;
+    private closeAnnounced;
+    private sdpHandled;
+    private chain;
+    constructor(opts: RtcSessionOptions);
+    get isConnected(): boolean;
+    /**
+     * Start the sequence; resolves once the call is sent. `connected` fires when the channel opens. A session
+     * closed by the time the sign fetch or the auth completes rejects instead of opening the socket or
+     * placing the call.
+     */
+    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.
+     */
+    close(): void;
+    /**
+     * Trickle one local candidate, or the empty end-of-candidates. The native peer can report one after the
+     * signalling socket has closed, and sending then throws inside a native callback, where the throw can't
+     * be caught and aborts the process. A candidate with no open socket is dropped.
+     */
+    private trickle;
+    private announceClose;
+    private waitForAuth;
+    /** Settle a pending auth wait: resolve it, or reject it with `err`; either way its timer stops. */
+    private settleAuth;
+    private onSignaling;
+    /** A `scall` status: `100` grants the relay, `200` is acknowledged, `486`/`408` fail the session. */
+    private onCall;
+    /**
+     * An `info`: trickle ICE, in either of the two shapes the hub sends, or the hub's SDP offer. The offer
+     * is answered only once a TURN grant is in: the peer is relay-only, so an offer ahead of `scall 100`
+     * is reported and left unanswered.
+     */
+    private onInfo;
+}

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

@@ -0,0 +1,139 @@
+/**
+ * The T9000's signalling channel: the WebSocket through which a client and a HomeBase S1 Pro agree on a
+ * WebRTC session. It is the wire the security.eufy.com web client uses (`/v1/rtc/ws/join`), and the hub
+ * accepts it from any client presenting the account's mega token.
+ *
+ * Sequence:
+ *
+ *   1. `GET https://<smart host>/v1/smart/nvr/ws/sign` with the mega token → a `sign` blob.
+ *   2. WebSocket to `wss://<smart host>/v1/rtc/ws/join?reqtype=nvr`, subprotocols `["v1", <base64url
+ *      JSON>]` carrying the cluster region, station serial, token, `gtoken` and the sign. HTTP headers on
+ *      the upgrade alone are refused: the JSON subprotocol is what authenticates.
+ *   3. `action 1` auth on open; `action 3` session messages after: `scall` (start), `info` (SDP and
+ *      trickle ICE), `ack`, `hangup`. Every session message carries an HMAC-SHA256 `account` over
+ *      `channelId + adminUserId + ts`, keyed by the token.
+ *
+ * Region is two values: the HTTP sign request names the account's **country** (`Web-Country`), the
+ * WebSocket payload names the **cluster**, the shard prefix uppercased (`ie-pr` → `IE`). The smart host
+ * is `security-smart` for `us` and `security-smart-<prefix>` for any other shard.
+ *
+ * `fetch` and the `WebSocket` constructor are injectable.
+ */
+import { EventEmitter } from "node:events";
+import { type Logger } from "../../core/logger.js";
+/** The portal's origin; the sign endpoint and the socket upgrade both check it. */
+export declare const PORTAL_ORIGIN = "https://security.eufy.com";
+/** The hub drops an idle signalling socket after ~83 s; re-sending auth inside that keeps it. */
+export declare const SIGNALING_KEEPALIVE_MS = 25000;
+/** How long the socket has to open after the sign. */
+export declare const SIGNALING_CONNECT_TIMEOUT_MS = 15000;
+/** Outer wire envelope. */
+export interface RtcWsEnvelope {
+    msgid: string;
+    data: string;
+}
+/** Inner message (the envelope's `data`, JSON-parsed). */
+export interface RtcInnerMessage {
+    code?: number;
+    action?: number;
+    sessionId?: string;
+    sn?: string;
+    subSn?: string;
+    channelId?: number;
+    isResponse?: number;
+    dataType?: string;
+    source?: string;
+    ts?: number;
+    data?: string;
+    msgid?: string;
+}
+/** What a socket event carries; only the fields each event type fills are read. */
+export interface SignalingSocketEvent {
+    data?: unknown;
+    code?: number;
+    reason?: string;
+}
+/** The subset of a `WebSocket` the client uses. */
+export interface SignalingSocket {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: "open" | "message" | "close" | "error", listener: (ev: SignalingSocketEvent) => void): void;
+}
+export interface SignalingSocketInit {
+    /** The subprotocols; slot 2 carries the base64url auth JSON. */
+    protocols: string[];
+    /** The upgrade Origin, which the server checks like the sign call. */
+    origin: string;
+}
+export type SignalingSocketFactory = (url: string, init: SignalingSocketInit) => SignalingSocket;
+export interface RtcSignalingOptions {
+    /** Full SDP (`call`) or compact SDP (`scall`, the default). */
+    signalingMode?: "call" | "scall";
+    /** The mega session's auth token. */
+    authToken: string;
+    /** The `gtoken` header value the mega session's authed HTTP calls carry. */
+    gtoken: string;
+    stationSn: string;
+    /** The station's `member.admin_user_id`, the account the session HMAC names. */
+    adminUserId: string;
+    /** The mega shard the account lives on; picks the host and the cluster name. */
+    shard: string;
+    /** The account's ISO country, sent on the sign request (`Web-Country`). */
+    country: string;
+    fetch?: typeof fetch;
+    createSocket?: SignalingSocketFactory;
+    logger?: Logger;
+    now?: () => number;
+    makeMsgId?: () => string;
+}
+export interface RtcSignalingEvents {
+    message: [inner: RtcInnerMessage, envelope: RtcWsEnvelope];
+    open: [];
+    close: [code: number, reason: string];
+    error: [err: Error];
+}
+/** The portal's `account` field: HMAC-SHA256 of `channelId + adminUserId + ts`, keyed by the token. */
+export declare function sessionAccount(channelId: number, adminUserId: string, ts: number, authToken: string): string;
+export declare class RtcSignalingClient extends EventEmitter<RtcSignalingEvents> {
+    private readonly opts;
+    private ws?;
+    private sign?;
+    private keepalive?;
+    private readonly wsUrl;
+    private readonly signUrl;
+    private readonly wsRegion;
+    private readonly fetchImpl;
+    private readonly createSocket;
+    private readonly logger;
+    private readonly now;
+    private readonly makeMsgId;
+    constructor(opts: RtcSignalingOptions);
+    get isOpen(): boolean;
+    /** Step 1: the sign blob the socket and every auth message carry. A non-JSON body is reported by status. */
+    fetchSign(): Promise<string>;
+    /**
+     * Step 2: open the socket and send the first auth; resolves on `open`. A socket that closes or errors
+     * before it ever opened rejects, so the call always settles.
+     */
+    connect(): Promise<void>;
+    /** `action 1`, also what keeps the socket alive when re-sent. */
+    sendAuth(sign?: string): void;
+    /**
+     * `action 3`, a session message on channel 0, the hub's own session; `scall` opens the negotiation.
+     * `subSn` is empty for the hub's session.
+     */
+    sendSession(dataType: string, payload?: Record<string, unknown>): void;
+    sendCall(): void;
+    sendAck(): void;
+    /** The SDP answer, encoded for the negotiated call format, in an `info`. */
+    sendInfoSdp(sdp: string): void;
+    /** Trickle a candidate on the session's channel, like its SDP answer. An empty candidate ends them. */
+    sendInfoCandidate(candidate: string): void;
+    sendHangup(): void;
+    close(): void;
+    private startKeepalive;
+    private stopKeepalive;
+    private sendEnvelope;
+    private handleWireMessage;
+}

package/dist/transport/token-echo.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Strip a token the gateway echoed back into its own error message.
+ *
+ * `"token not exist, token = <the rejected token>"` is the vendor's wording, and that message travels into the
+ * error the SDK surfaces. A credential that has just been rejected is still a credential, and it is
+ * never the part of the message that explains anything.
+ */
+export declare function withoutTokenEcho(text: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mega-yfue/eufy-sdk",
-  "version": "0.5.0-beta.5",
+  "version": "0.5.0-beta.50",
   "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",
@@ -74,6 +74,7 @@
   "dependencies": {
     "jpeg-js": "^0.4.4",
     "mqtt": "^5.16.0",
+    "node-datachannel": "^0.33.4",
     "protobufjs": "^8.8.0"
   },
   "devDependencies": {