@mega-yfue/eufy-sdk 0.5.0-beta.2 → 0.5.0-beta.20

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

@@ -8,6 +8,8 @@ import { type Command, type MediaProvider } from "../../core/contracts.js";
  * `transport/p2p/commands.ts`). Each entry notes its app `CommandType` name.
  */
 export declare const CAMERA_CMD: {
+    /** Camera-reported Wi-Fi signal (app `CMD_GET_WIFI_RSSI`). */
+    readonly WIFI_RSSI: 1142;
     /** Camera on/off. Read and write polarity depend on the family and topology. */
     readonly CAMERA_ENABLE: 1035;
     /** Wrapped T8410 power switch on HomeBase 3. */
@@ -271,6 +273,14 @@ export type CameraActions = Surface<typeof CAMERA_MEMBERS> & {
  * @internal
  */
 export declare const CAMERA_MEMBERS: {
+    /** Reads the latest cached report and exposes no setter. */
+    readonly wifiRssi: {
+        readonly param: 1142;
+        readonly type: "number";
+        readonly kind: "scalar";
+        readonly provenance: "apk";
+        readonly description: "Camera-reported Wi-Fi signal; physical units and a quality scale are unspecified.";
+    };
     /**
      * The default READ is the *disable*-bit convention (1035 "0" ⇒ ON, 2001 direct); the WRITE polarity is
      * family-dependent — see `powerValue` / `isEnableBitPolarity`. Battery/solo cams report the state under
@@ -435,25 +445,29 @@ export declare const CAMERA_MEMBERS: {
      * Live-view quality, the pair to {@link CAMERA_MEMBERS.recordingQuality} and a different setting on a
      * different wire: changing one leaves the other's parameter untouched.
      *
-     * The READ is 1020, which reports the resolved tier as a plain integer. 1020 is also the name the
-     * param dictionary already gives that id, and `Device` keys state by NAME — a member claiming 2730
-     * under this name would collide with it on a device reporting both.
+     * The READ is 1020, which reports the resolved tier as a plain integer, while the WRITE rides 2730's
+     * `1350` payload. They are two ids for one setting because 2730 carries a per-mode config and 1020
+     * carries the tier in force; the tier is what this property means. 1020 is also the name the param
+     * dictionary already gives that id, and `Device` keys state by NAME — a member claiming 2730 under
+     * this name would collide with it on a device reporting both.
      *
-     * `unverified: true` with no `write`: the app's 2730 frame is captured byte-exact, but replaying it
-     * from this SDK produced no observable change on a standalone T8171, where the recording sibling's
-     * 2731 write on the same envelope and the same session does land. The one difference the capture
-     * shows is that the app's frame carries no `mChannel`/`mValue3`, which this envelope always emits.
-     * Until a send is confirmed, the setter is absent — a control that silently does nothing is worse
-     * than none — and the read ships ahead of it, which verification per direction allows.
+     * `transaction` is part of the frame that was captured, so it is sent. The recording sibling's own
+     * confirmed frame carries no such field; neither is inferred from the other.
      */
     readonly streamingQuality: {
+        readonly accepts: StreamingQualityName;
         readonly param: 1020;
         readonly type: "number";
         readonly kind: "enum";
         readonly enumValues: Readonly<Record<number, string>>;
         readonly provenance: "verified";
-        readonly unverified: true;
+        readonly args: readonly [{
+            readonly name: "quality";
+            readonly kind: "enum";
+            readonly description: "A tier, or the name it maps to. 0 is Auto.";
+        }];
         readonly description: string;
+        readonly write: (v: string | number | boolean, ctx: CommandContext) => Command | undefined;
     };
     /**
      * `type` is how the value is STORED, and 2731 stores the whole config — the ACTIVE tier is lifted out

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

@@ -160,6 +160,9 @@ export declare const LIGHT_MEMBERS: {
      * This is the switch a user changes and expects to STAY changed. {@link isOn} is a different fact:
      * the lamp being lit right now, driven by whichever
      * client is streaming — the vendor app lights it for a live view and drops it on quitting.
+     *
+     * The T8423 write takes the session-chosen level; level-1 int+string was verified live on a standalone
+     * unit.
      */
     readonly spotlightEnabled: {
         readonly param: 1403;

package/dist/model/capabilities/vacuum-clean.d.ts

@@ -169,12 +169,11 @@ export declare const TUYA_CLEAN_TYPES: readonly ["Sweep", "SweepMop", "Mop"];
 /** @internal */
 export type TuyaCleanType = (typeof TUYA_CLEAN_TYPES)[number];
 /**
- * `ModeCtrlRequest.method` values for DP 152. Live-verified on T2351: START_AUTO_CLEAN → 0
- * (omitted from the wire when zero), START_GOHOME → 6, PAUSE_TASK → 13.
+ * `ModeCtrlRequest.method` values for DP 152. Live-verified on T2351: START_GOHOME → 6,
+ * PAUSE_TASK → 13. An auto clean is `START_AUTO_CLEAN` (0) with a payload — see
+ * {@link ModeCtrlParamMethod}.
  */
 export declare const ModeCtrlMethod: {
-    /** Live-verified on a T2351. Zero, so it is omitted from the wire per the proto3 default rule. */
-    readonly START_AUTO_CLEAN: 0;
     /** Live-verified on a T2351. */
     readonly START_GOHOME: 6;
     /** Live-verified on a T2351. */
@@ -202,9 +201,11 @@ export declare const ModeCtrlMethod: {
  * its argument in the signature: {@link VACUUM_CLEAN_MEMBERS.startScene},
  * {@link VACUUM_CLEAN_MEMBERS.cleanRooms} and {@link VACUUM_CLEAN_MEMBERS.cleanZones}.
  *
- * The outer frame these ride in is byte-verified on a live T2351, and `SCENE`, `SELECT_ROOMS` and
- * `SELECT_ZONES` have each since been RUN on a T2351 and did what they name — so their numbers rest on
- * observed behaviour rather than on the vendor's definition alone.
+ * The outer frame these ride in is byte-verified on a live T2351, and `AUTO`, `SCENE`, `SELECT_ROOMS`
+ * and `SELECT_ZONES` have each since been RUN on a T2351 and did what they name — so their numbers rest
+ * on observed behaviour rather than on the vendor's definition alone. `AUTO` is RUN with its payload:
+ * the vendor's definition calls `AutoClean.clean_times` valid only when non-zero, and the T2351 did
+ * not start on method 0 sent without it.
  *
  * That distinction is the whole point of checking, and this is the one place it is argued: an AIoT
  * data-point write is fire-and-forget, so a wrong number would be a different command arriving and
@@ -215,6 +216,11 @@ export declare const ModeCtrlMethod: {
  * scene id and a map id both arrive on DP 180.
  */
 export declare const ModeCtrlParamMethod: {
+    /** `START_AUTO_CLEAN` with an `AutoClean` payload — clean the whole floor. */
+    readonly AUTO: {
+        readonly method: 0;
+        readonly param: 3;
+    };
     /** `START_SELECT_ROOMS_CLEAN` — clean the named rooms of a named map. */
     readonly SELECT_ROOMS: {
         readonly method: 1;
@@ -274,17 +280,17 @@ export declare function encodeSelectZonesClean(mapId: number, zones: readonly Va
  * @internal
  */
 export declare function encodeSceneClean(sceneId: number): string;
+/**
+ * Build a whole-floor auto clean carrying an `AutoClean` payload of one pass.
+ * @internal
+ */
+export declare function encodeAutoClean(): string;
 /**
  * Encode a `ModeCtrlRequest` protobuf (DP 152) as a DP value: `varint(bodyLen) ++ {method:1, seq:2}`.
  *
  * Built on {@link RawDpWriter} rather than hand-rolled bytes. The frame is unchanged and the existing
  * byte-level test is what proves it — that test was written against a live T2351 capture, so it holds
  * the writer to the wire rather than to this function's own idea of the wire.
- *
- * Method 0 (START_AUTO_CLEAN) is omitted rather than written as an explicit zero, per the proto3
- * default-field rule and confirmed on that same capture. The writer deliberately does not apply that
- * rule itself: whether an explicit zero and an absent field mean the same thing is the
- * message's business, not the encoder's.
  * @internal
  */
 export declare function encodeModeCtrl(method: number, seq: number): string;
@@ -1955,7 +1961,7 @@ export declare const VACUUM_CLEAN_MEMBERS: {
         readonly provenance: "mega";
         readonly description: "Stop smart-follow mode (ModeCtrlRequest method 18 over DP 152). Method number not captured — unverified.";
     };
-    /** Start an auto-clean run via ModeCtrlRequest method 0 (DP 152). AIoT only — Tuya write unverified. */
+    /** Start an auto-clean run via ModeCtrlRequest method 0 with one `AutoClean` pass (DP 152). AIoT only — Tuya write unverified. */
     readonly startCleaning: import("./members.js").MethodMember<() => Promise<void>> & {
         available: (ctx: import("./types.js").CommandContext) => boolean;
     };

package/dist/model/device-family.d.ts

@@ -43,6 +43,8 @@ export declare const isOutdoorPanTilt: (ctx: FamilyContext) => boolean;
 export declare const isFloodLight: (ctx: FamilyContext) => boolean;
 /** HomeBase-family hub (has a speaker/alarm) — a station EXCLUDING the NVRs, per `HOMEBASE_TYPES`. */
 export declare const isHomeBase: (ctx: FamilyContext) => boolean;
+/** HomeBase S1 Pro (`STATION_9000`), the station the app drives over its WebRTC control channel. */
+export declare const isStation9000: (ctx: FamilyContext) => boolean;
 /** Wired doorbell (DeviceType.DOORBELL). */
 export declare const isWiredDoorbell: (ctx: FamilyContext) => boolean;
 /**

package/dist/model/registry.d.ts

@@ -48,7 +48,8 @@ export declare function resolveDevice(rec: CloudRecord): ResolvedDevice;
  * The property manifest for a device, from its capabilities and the record's facts. The single place
  * an {@link AvailabilityContext} is built — so a family-gate (`available`) and a per-model enum
  * (`enumValuesFor`) are decided from the same truthful, session-free view on every path (initial
- * resolve and {@link Device.reresolve}). Populated only from what a record carries, never transport
- * fields a live session hasn't produced.
+ * resolve and {@link Device.reresolve}). Populated only from what a record carries: its cloud params and
+ * the params its device reported over realtime, the same evidence a bound getter is gated on. Never
+ * transport fields a live session hasn't produced.
  */
 export declare function resolveProperties(rec: CloudRecord, codec: Codec, capabilities: Capability[]): PropertySpec[];

package/dist/model/types.d.ts

@@ -286,6 +286,12 @@ export interface CloudRecord {
     parentSn?: string;
     /** Reported param_type → raw value. Presence of a param is a capability signal. */
     params?: Record<number, string>;
+    /**
+     * Params the device reported over its realtime channel, keyed in the device's own namespace. A line
+     * whose state exists only on that channel carries none of it in {@link params}, so this is the
+     * evidence an availability gate on such a param is decided from.
+     */
+    dpParams?: Record<number, string>;
 }
 /** The fully-resolved device shape produced by the 3-tier resolver. */
 export interface ResolvedDevice {

package/dist/transport/http/mega-client.d.ts

@@ -209,6 +209,8 @@ export interface SignedRetry {
 export declare class MegaHttpClient {
     private readonly cfg;
     private region;
+    /** The host `estimate_domain` answered, persisted with the session. */
+    private estimatedDomain;
     private bootstrapDomain?;
     private sessionKey?;
     /** Per-host ECDH session keys for non-mega gateways (e.g. eufylife) keyed by host. */
@@ -275,6 +277,21 @@ export declare class MegaHttpClient {
     } | undefined;
     /** The active region shard (e.g. `"eu-pr"`, `"us-pr"`), set after {@link login} or a region override. */
     get regionShard(): RegionShard;
+    /**
+     * The shard the RTC signalling signs on: the regional prefix of the estimated domain
+     * (`…-ie-…`/`…-ie.` → `ie-pr`), else {@link regionShard}. The eu/us classification cannot name shards
+     * like `ie-pr`, whose accounts need the IE sign host and cluster.
+     */
+    get rtcShard(): string;
+    /**
+     * The credentials the RTC signalling needs; `undefined` while logged out. The sign is refused
+     * ("gtoken not equal userid") unless its gtoken is the one every authed HTTP call carries.
+     */
+    rtcIdentity(): {
+        authToken: string;
+        userId: string;
+        gtoken: string;
+    } | undefined;
     /**
      * The name commands attribute themselves to — {@link MegaClientConfig.accountName} when the config
      * pins one (trimmed; blank counts as unset), otherwise the logged-in account's display name, which
@@ -367,6 +384,15 @@ export declare class MegaHttpClient {
      * params instead, which also carry `{param_type, param_value, update_time}` and are not owner-gated.
      */
     getDeviceParamList<T = unknown>(deviceSn: string): Promise<T>;
+    /**
+     * Fetch the account's devices as the `devicerelation` service lists them, `{attribute: 7, house_id: ""}`.
+     *
+     * Each entry is `{device: {device_sn, dps, …}}`, and `dps` is the cloud's last-known value of every
+     * data point that device has reported, keyed by DP number. Answered for an account a device is shared
+     * with as well as for its owner. Sent with `category: eufy_home`, without which the service answers
+     * `10000`.
+     */
+    getDeviceRelationList<T = unknown>(): Promise<T>;
     /**
      * Fetch one page of a device's **cleaning history** from the mega `clean` service.
      *

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

@@ -258,11 +258,14 @@ export declare class P2PCommandRouter {
      */
     dispatchCommand(sn: string, cmd: Command): Promise<void>;
     /**
-     * Restart a HomeBase. `RESTART_HUB` (1034) is a station-scalar on the broadcast channel 255: a
-     * level-2 frame whose body is `[u32 value][account_id padded]` — the same shape as the hub
-     * alarm-volume control. ✅ Wire-confirmed byte-exact from a capture of the app's own Restart
-     * (2026-08-03) and HW-tested: the captured frame carried value `0` and rebooted the hub. Replays
-     * like every other level-2 control, so a single dropped datagram doesn't lose it.
+     * Restart the station that owns `sn`'s P2P session. `RESTART_HUB` (1034) is a station-scalar on the
+     * broadcast channel 255 whose body is `[u32 value][account_id padded]`, value `0`. ✅ Wire-confirmed
+     * byte-exact as a level-2 frame from a capture of the app's own HomeBase Restart (2026-08-03).
+     *
+     * The seal follows the session, as {@link sendBySessionLevel} defines it: a keyed session takes the
+     * level-2 frame, a keyless one — a standalone camera, which never negotiates a key — the same body
+     * sealed level-1. Both are replayed {@link DIRECT_CMD_SENDS}× at 200ms, as every other unacknowledged
+     * control here is.
      */
     rebootStation(sn: string): Promise<void>;
     /**
@@ -308,6 +311,11 @@ export declare class P2PCommandRouter {
      * stream costs nothing extra and a talkback on an otherwise idle camera opens the session it needs
      * instead of playing into silence.
      *
+     * **On a model in {@link ELD_TALKBACK_MODELS}, the speaker plays the codec the camera sends.** So the first
+     * audio frame of the media session this talkback holds decides its codec ({@link speakerCodec}), within
+     * {@link TALKBACK_CODEC_WAIT_MS} of the session's first frame, and the claim is re-checked after that wait as
+     * after the warm-up. Every other model opens `aac-lc` at once.
+     *
      * The level-2 key is waited for softly: only the HomeBase-attached path requires it, and
      * {@link Talkback.start} reports that failure precisely, so a hard wait here would reject an
      * own-session camera that legitimately never negotiates one.

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

@@ -20,6 +20,8 @@ export declare class Fmp4Muxer {
     private lastVideoTimestampMs?;
     private readonly audioRequested;
     private audioCodec?;
+    /** Decoder config of an AAC-ELD track, taken from its frames; absent for AAC-LC, whose `esds` config is fixed. */
+    private audioConfig?;
     private audioDisabled;
     private audioSamples;
     private audioBaseDecodeTime;
@@ -37,7 +39,10 @@ export declare class Fmp4Muxer {
      * (e.g. delta frames before the first keyframe).
      */
     push(frame: LiveVideoFrame, timestampMs?: number): MediaFragment | undefined;
-    /** Add one station-declared AAC access unit to the audio track. G.711 remains available via `live()`. */
+    /**
+     * Add one station-declared AAC access unit to the audio track: an ADTS frame for AAC-LC, a raw access unit
+     * described by its frame's config for AAC-ELD. G.711 remains available via `live()`.
+     */
     pushAudio(frame: LiveAudioFrame, timestampMs?: number): MediaFragment | undefined;
     /** Permanently omit incompatible audio while allowing the video recording to continue. */
     private disableAudio;

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

@@ -103,6 +103,9 @@ export declare class LiveStream extends EventEmitter {
     private lastCodec;
     /** Rebuilds an access unit the station split across several frames — see {@link AccessUnitAssembler}. */
     private readonly units;
+    /** Whether a missing video datagram or incomplete unit invalidated the current reference chain. */
+    private awaitingKeyframeAfterGap;
+    private readonly videoGapHandler;
     /** The channel inbound media must be tagged with, once {@link acceptsMedia} trusts the station's tag. */
     private mediaChannel?;
     private tracedFirstVideoCommand;

package/dist/transport/p2p/p2p-session.d.ts

@@ -277,8 +277,8 @@ export declare class P2PSession extends EventEmitter {
     private decryptLevel2;
     get isConnected(): boolean;
     /**
-     * Ask the OS for {@link RECEIVE_BUFFER_BYTES} on a bound socket, and warn once per session when it grants
-     * less or refuses.
+     * Ask the OS for {@link RECEIVE_BUFFER_BYTES} on a bound socket, and log once per session when it grants
+     * less (debug) or refuses (warn).
      *
      * The request is made here rather than through `createSocket`'s `recvBufferSize`: Node applies that option
      * inside the bind callback, where a refusal is thrown out of reach of this session and ends the process.
@@ -435,6 +435,11 @@ export declare class P2PSession extends EventEmitter {
      * "direct" commands (e.g. CAMERA_SWITCH 1035) carry a binary struct, not JSON.
      */
     sendRawLevel2Bytes(payload: Buffer, channel: number, outerCmd?: number, signCode?: number): boolean;
+    /**
+     * The level-1 twin of {@link sendRawLevel2Bytes}: the plaintext `payload` sealed AES-128-ECB under the
+     * level-1 key, signCode 1 — the seal of the level-1 media start. Returns `false` when not connected.
+     */
+    sendRawLevel1Bytes(payload: Buffer, channel: number, outerCmd: number): boolean;
     /**
      * Stop the realtime media stream (`CMD_STOP_REALTIME_MEDIA`, 1004) on a camera `channel`, in the shape
      * its runtime topology takes, as {@link startLiveMedia} selects its start:

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

@@ -1,10 +1,12 @@
 /**
- * Managed talkback session over P2P — the send-side twin of `live-stream.ts`. Takes AAC-LC audio from
- * a host, recovers frame boundaries, and paces the frames onto the wire at their own playback rate,
- * bracketed by the device's start/stop control frames.
+ * Managed talkback session over P2P — the send-side twin of `live-stream.ts`. Takes audio from a host in
+ * the codec the camera's speaker plays (AAC-LC ADTS, or raw AAC-ELD access units), recovers frame
+ * boundaries, and paces the frames onto the wire at their own playback rate, bracketed by the device's
+ * start/stop control frames.
  *
  * Pacing is the reason this exists rather than a bare `sendAudioFrame` loop. Each AAC-LC frame at
- * 16 kHz is 1024 samples — exactly 64 ms of audio — and the device plays what arrives when it arrives.
+ * 16 kHz is 1024 samples — exactly 64 ms of audio — and each AAC-ELD access unit is 512 samples, 32 ms.
+ * The device plays what arrives when it arrives.
  * A host piping a file would otherwise deliver a minute of audio in a few hundred milliseconds and
  * lose all but the tail. A live source paces itself and simply keeps the queue near-empty.
  *
@@ -17,7 +19,7 @@
  */
 import { EventEmitter } from "node:events";
 import { Writable } from "node:stream";
-import type { AacEncoder, StreamBudgetNotice, TalkbackHandle } from "../../core/contracts.js";
+import type { AacEncoder, StreamBudgetNotice, TalkbackCodec, TalkbackHandle } from "../../core/contracts.js";
 import { type Logger } from "../../core/logger.js";
 /**
  * The subset of the session this needs — start/stop the path, push one frame, and report a frame the
@@ -66,7 +68,7 @@ export interface TalkbackOptions {
 export declare const DEFAULT_IDLE_TIMEOUT_MS = 30000;
 /**
  * A talkback session bound to one camera channel. Opens the device's path on construction via
- * {@link start}, then drains queued frames on a fixed 64 ms tick until {@link stop}.
+ * {@link start}, then drains queued frames on a tick of one frame's duration until {@link stop}.
  */
 export declare class Talkback extends EventEmitter implements TalkbackHandle {
     private readonly sink;
@@ -74,7 +76,8 @@ export declare class Talkback extends EventEmitter implements TalkbackHandle {
     private readonly reader;
     private readonly queue;
     private readonly logger;
-    private readonly highWater;
+    /** Playback duration of one queued frame, the pacer's step: 64 ms for `aac-lc`, 32 ms for `aac-eld`. */
+    private frameMs;
     private readonly idleTimeoutMs;
     private timer?;
     private started;
@@ -94,17 +97,24 @@ export declare class Talkback extends EventEmitter implements TalkbackHandle {
     private chain;
     private readonly onAudioGap;
     constructor(sink: TalkbackSink, opts: TalkbackOptions);
+    /** Frames the pacing queue holds before a writable applies backpressure: {@link HIGH_WATER_MS} of this codec. */
+    private get highWater();
+    /** The codec this talkback sends, set by {@link start}. */
+    codec: TalkbackCodec;
     /** Frames still queued for the wire. */
     get pending(): number;
     /**
      * Open the device's talkback path and begin the pacing tick. Throws when the topology's control
      * frame could not be sent — for a HomeBase-attached camera that means the level-2 key was never
      * negotiated, which would otherwise leave a silent session that accepts audio nobody hears.
+     *
+     * `codec` is the codec the camera's speaker plays; it fixes the input this talkback accepts and the pacing step.
      */
-    start(): this;
+    start(codec: TalkbackCodec): this;
     /**
-     * Queue audio. Bytes are ADTS AAC, or PCM when an encoder was supplied; either way the input is
-     * treated as a stream, so a chunk carrying part of a frame is held until the rest arrives.
+     * Queue audio in the codec this talkback sends. For `aac-lc` the bytes are ADTS, or PCM when an encoder was
+     * supplied, read as a stream, so a chunk carrying part of a frame is held until the rest arrives. For `aac-eld`
+     * each call is one whole access unit; a unit over the device's length limit is dropped with an `error`.
      *
      * Audio written after {@link end} is dropped with an `error` rather than queued: `finished` has
      * either already fired or is owed on the frames written before it, so a late chunk would either play
@@ -160,6 +170,7 @@ export declare class Talkback extends EventEmitter implements TalkbackHandle {
     /**
      * A Writable over {@link write} that withholds its callback while the queue is at the high-water
      * mark — which is what turns `pipe()` from a file into playback at speed rather than a memory spike.
+     * For `aac-eld` it is object-mode: each write is one access unit.
      */
     writable(): Writable;
     /** Drain an encoder's partial trailing block, so the last syllable is not lost. */

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

@@ -144,9 +144,10 @@ export declare class AccessUnitAssembler {
      * `decode` extracts the payload of a frame, whatever the stream's encryption: it is called for EVERY
      * frame, including a continuation, because a continuation carries its own wrapped key ahead of its share
      * of the payload (measured: 129 bytes beyond what its header declares, exactly as a unit's first frame
-     * carries).
+     * carries). A continuation without its matching open unit has no Annex-B start code and cannot be emitted
+     * as a complete unit, even if its repeated header says keyframe.
      */
     push(payload: Buffer, decode: (payload: Buffer) => Buffer | undefined): AssembledAccessUnit[];
     /** Forget an incomplete unit, counting and reporting it. */
-    private discard;
+    discard(): void;
 }

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

@@ -0,0 +1,72 @@
+/**
+ * RTC command router: drives a **HomeBase S1 Pro (T9000)** over the portal's WebRTC data channel instead
+ * of P2P.
+ *
+ * The T9000 answers no P2P lookup, but it accepts the portal's control channel: sign → WS join → scall →
+ * SDP answer → ICE over the relay the hub grants → DTLS → SCTP data channels, with commands riding
+ * `WebrtcDataChannel` as portal packets (see {@link buildPortalPacket}).
+ *
+ * `set-payload` rides the `1350` SET_PAYLOAD envelope, inner `{account_id, cmd, mValue3, payload}`;
+ * `set-json` rides the `1700` CONTROL_PAYLOAD envelope, inner `{account_id, cmd, commandType, data}`.
+ * 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.
+ */
+import type { Command } from "../../core/contracts.js";
+import type { Logger } from "../../core/logger.js";
+import { RtcSession, type RtcSessionOptions } from "./session.js";
+export interface RtcIdentity {
+    authToken: string;
+    userId: string;
+    /** The `gtoken` header value the mega session's authed HTTP calls carry. */
+    gtoken: string;
+}
+/** Where a command goes: the station's session, and whether it addresses the station or a device on it. */
+export interface RtcRoute {
+    stationSn: string;
+    /**
+     * The station's `member.admin_user_id`, the account the session and the payload name; the logged-in
+     * user when the station's record carries none.
+     */
+    adminUserId?: string;
+    /** True for a device attached to the station, which keeps the command's own channel. */
+    attached: boolean;
+}
+export interface RtcCommandRouterDeps {
+    /** The logged-in session's credentials; `undefined` while logged out. */
+    identity: () => RtcIdentity | undefined;
+    /** The mega shard the account signs on (`"ie-pr"`, `"eu-pr"`, `"us-pr"`); picks the smart host. */
+    shard: () => string;
+    /** ISO country sent on the sign request (default `US`). */
+    country?: string;
+    logger?: Logger;
+    onError?: (e: Error) => void;
+    createSession?: (opts: RtcSessionOptions) => RtcSession;
+}
+export declare class RtcCommandRouter {
+    private readonly deps;
+    private readonly sessions;
+    constructor(deps: RtcCommandRouterDeps);
+    dispatchCommand(route: RtcRoute, cmd: Command): Promise<void>;
+    /** Tear down every station session (logout / shutdown). */
+    close(): void;
+    /**
+     * 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
+     * not establish physical actuation. The command is sent once, bounded by {@link ACK_TIMEOUT_MS}.
+     */
+    private sendAwaitAck;
+    private stationSession;
+    /**
+     * One bounded bring-up: the session is up when its command channel opens, and it fails, with the
+     * session closed and every listener gone, when `connect()` throws, the session closes first, or
+     * {@link CONNECT_TIMEOUT_MS} passes. A single promise, so an early failure cannot leave a second one
+     * rejecting unheard.
+     */
+    private bringUp;
+    private touch;
+    private drop;
+}

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

@@ -0,0 +1,93 @@
+/**
+ * The WebRTC peer for a T9000 session: libdatachannel through `node-datachannel`, driven the way the
+ * portal drives a browser's RTCPeerConnection.
+ *
+ * The hub is the offerer: it sends its SDP once it has granted the session, and the peer answers. Six
+ * data channels are declared in the portal's order (`WebrtcDataChannel` first, the command channel,
+ * then audio, idr, video, notify, download). Every one carries PTCS-framed portal packets; which logical
+ * channel a reassembled frame belongs to is the PTCS header's channel, not the data channel it rode on.
+ *
+ * ICE is relay-only. The hub grants a TURN allocation in its `scall 100` reply and completes DTLS only
+ * over the relay pair; on a host pair ICE connects and the DTLS handshake never completes. The peer
+ * plays the DTLS client (`active`) and opens its channels on the client's even SCTP stream ids, which
+ * is what the hub pairs with.
+ *
+ * The native peer is injectable.
+ */
+import { EventEmitter } from "node:events";
+import type { PeerConnection, RtcConfig } from "node-datachannel";
+import { type Logger } from "../../core/logger.js";
+export interface TurnConfig {
+    turn_addr: string;
+    turn_port: number;
+    turn_user: string;
+    turn_password: string;
+    alt_turn_addr?: string;
+    alt_turn_port?: number;
+}
+export type NativePeerFactory = (name: string, config: RtcConfig) => PeerConnection;
+export interface RtcPeerOptions {
+    createPeer?: NativePeerFactory;
+    logger?: Logger;
+}
+export interface RtcPeerEvents {
+    commandChannelOpen: [];
+    /** The command channel went away while the peer itself may still be up. */
+    commandChannelClosed: [];
+    data: [frame: Buffer, linkType: number];
+    iceCandidate: [candidate: string];
+    iceGatheringComplete: [];
+    connectionState: [state: string];
+    error: [err: Error];
+}
+/** The portal's channel list; index 0 is the command channel. */
+export declare const DATA_CHANNEL_LABELS: readonly ["WebrtcDataChannel", "audio", "idr", "video", "notify", "download"];
+export declare const COMMAND_CHANNEL: "WebrtcDataChannel";
+export declare class RtcPeer extends EventEmitter<RtcPeerEvents> {
+    private readonly opts;
+    private pc?;
+    private readonly channels;
+    private framer?;
+    private readonly wireTally;
+    private commandOpen;
+    private remoteSet;
+    private handlingOffer;
+    private channelsCreated;
+    private gatheringDone;
+    /** Set by the framer's wire callback when the native channel refused a packet mid-send. */
+    private wireSendFailed;
+    private readonly pending;
+    private localAnswer?;
+    private readonly logger;
+    constructor(opts?: RtcPeerOptions);
+    /** Create the native peer on the relay the hub granted in `scall 100`. */
+    init(turn: TurnConfig): Promise<void>;
+    /**
+     * The hub offered: apply the offer, declare the channels, return the answer SDP to signal back.
+     *
+     * The offer is pinned to `passive` before it is applied, so the native peer has one legal answer,
+     * `active`: the role is fixed where it is decided, since rewriting the answer afterwards would change
+     * only what is announced. The offer goes in before the channels are declared: `createDataChannel` on
+     * a peer without a remote description starts its own negotiation and leaves it in `have-local-offer`.
+     * The data channels need no m-line of their own; the offer's SCTP m-line carries them. Only an ANSWER
+     * is taken as the local description: one read in `have-local-offer` is an offer.
+     */
+    handleRemoteOffer(offerSdp: string): Promise<string>;
+    addRemoteCandidate(candidate: string): void;
+    /**
+     * 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.
+     */
+    sendCommand(portalPacket: Buffer): boolean;
+    /** Tear the peer down. A pending answer is rejected, so a `handleRemoteOffer` in flight settles. */
+    close(): void;
+    private acceptsCandidate;
+    private createChannels;
+    /**
+     * Wire one data channel. Every channel feeds the framer once the command channel has opened it; a
+     * message before that has nothing to reassemble into and is dropped.
+     */
+    private wireChannel;
+    private addNow;
+    private flushPending;
+}