@mega-yfue/eufy-sdk 0.5.0-beta.8 → 0.5.0-beta.81

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

@@ -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/call-live.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Live view of a T8223 doorbell (Video Doorbell C31) over a portal `call` {@link RtcSession}.
+ *
+ * The doorbell is its own station and streams no PTCS framing: its video arrives as plain RTP on the
+ * offer's H.264 video m-line, which a {@link RtcPeerOptions.mediaTrack} peer hands over as `rtp`. This
+ * stream depacketizes it into whole Annex-B access units, one per frame. Each stream owns its session:
+ * starting it places the call, stopping it hangs up.
+ */
+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";
+/**
+ * H.264 RTP depacketizer (RFC 6184 single NAL / STAP-A / FU-A). Feed whole RTP packets; it calls `onUnit`
+ * with each complete Annex-B access unit when the marker bit closes it. A unit with a sequence gap or an
+ * unterminated fragment is dropped, never delivered short. RTCP multiplexed on the same transport (PT
+ * 200-207, which reads as 72-79 in the RTP payload-type bits) is skipped.
+ */
+export declare class H264Depacketizer {
+    private readonly onUnit;
+    private nals;
+    private fu;
+    private lastSeq;
+    private broken;
+    constructor(onUnit: (unit: Buffer, timestamp: number) => void);
+    push(packet: Buffer): void;
+}
+/** A `LiveStreamHandle` over one portal `call` to a T8223 doorbell. */
+export declare class RtcCallLiveStream extends EventEmitter implements LiveStreamHandle {
+    private readonly session;
+    private readonly logger;
+    private running;
+    private readonly depacketizer;
+    /** `session` is a session on a {@link RtcPeerOptions.mediaTrack} peer, not yet connected. */
+    constructor(session: RtcSession, logger?: Logger);
+    start(): this;
+    stop(): void;
+    private onUnit;
+    private fail;
+    private teardown;
+}

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

@@ -0,0 +1,145 @@
+/**
+ * RTC command router: drives a station 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;
+ * 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, type MediaProvider } 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 {
+    /** The station's signaling exchange; defaults to compact SDP. */
+    signalingMode?: "call" | "scall";
+    /** Candidate policy used by the station's exchange; defaults to relay-only. */
+    iceTransportPolicy?: "relay" | "all";
+    /**
+     * The station streams video as RTP on its offer's video track and serves no data channel, so it takes
+     * no portal command; see `RtcPeerOptions.mediaTrack`.
+     */
+    mediaTrack?: boolean;
+    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;
+}
+/** 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;
+    /** 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;
+    /** 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;
+    private readonly warm;
+    private readonly callSources;
+    constructor(deps: RtcCommandRouterDeps);
+    dispatchCommand(route: RtcRoute, cmd: Command): Promise<void>;
+    /**
+     * 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;
+    /**
+     * Live view of a station on a {@link RtcRoute.mediaTrack} route: a live feed, a readable feed and a live
+     * still, from one shared source per station whose every warm-up places a fresh `call` on its own
+     * session. Recording has no wire here and is refused.
+     */
+    trackMediaProviderFor(route: RtcRoute): MediaProvider;
+    /** NVR media uses a dedicated call per camera, independent of station commands. */
+    nvrMediaProviderFor(route: RtcLiveRoute, views: readonly number[]): MediaProvider;
+    /** Share a dedicated-call source and its consumer operations under one route key. */
+    private callMediaProviderFor;
+    /**
+     * 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
+     * not establish physical actuation. The command is sent once, bounded by {@link ACK_TIMEOUT_MS}.
+     */
+    private sendAwaitAck;
+    private newSession;
+    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 (rejecting
+     * with the failure that closed it, when it carries one), or {@link CONNECT_TIMEOUT_MS} passes. A single
+     * promise, so an early failure cannot leave a second one rejecting unheard.
+     */
+    private bringUp;
+    /**
+     * Hold a station's command session open: one hold per station, its idle-close ({@link IDLE_CLOSE_MS})
+     * suppressed, {@link PORTAL_KEEPALIVE} sent every {@link PORTAL_KEEPALIVE_MS}, and the session dropped
+     * on a tick that finds the previous keepalive unechoed. A closed session ends the hold.
+     *
+     * Answers an idempotent disposer that releases the hold. Throws when no account is logged in.
+     */
+    keepWarm(route: RtcRoute): () => void;
+    /**
+     * Bring a station session up for a {@link keepWarm} hold and start its keepalive. A bring-up that fails,
+     * or a hold disposed before it completes, clears the hold and arms no timer. Each tick first checks
+     * that the hub echoed the previous keepalive, and drops the session when it did not. The keepalive
+     * stops when the session closes, which also clears the hold so the next command or `keepWarm`
+     * rebuilds cleanly.
+     */
+    private warmUp;
+    /** Stop a hold's keepalive and remove its listeners from the session it watches. */
+    private unwatch;
+    private touch;
+    private drop;
+}

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

@@ -0,0 +1,76 @@
+/**
+ * A portal camera live pull: T9000 shares its control session, NVR media owns a dedicated call.
+ *
+ * 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.
+ *
+ * A session serves one live view on that play slot. 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;
+    /** NVR media owns and connects its session. */
+    nvr?: boolean;
+    /** Optical view carried by the NVR start request; defaults to 0. */
+    view?: number;
+}
+/**
+ * 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. Video is H.265 Annex B, keyframes being IDRs.
+ */
+export declare class RtcLiveStream extends EventEmitter implements LiveStreamHandle {
+    private readonly opts;
+    private running;
+    private startSegment;
+    private readonly onConnected;
+    private readonly onError;
+    private keepalive?;
+    private width;
+    private height;
+    private readonly onMedia;
+    private readonly onCommand;
+    private readonly onClose;
+    constructor(opts: RtcLiveOptions);
+    private get tag();
+    start(): this;
+    private sendStart;
+    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

@@ -0,0 +1,122 @@
+/**
+ * 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 defaults to relay-only. The T9000 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.
+ *
+ * With {@link RtcPeerOptions.mediaTrack} the remote is a T8223 doorbell instead: its offer bundles an Opus
+ * audio, an H.264 video and an `m=application` section, but it never completes the SCTP association. The
+ * application section is rejected before the offer is applied, no data channel is declared, and the
+ * video m-line's RTP is emitted as `rtp`.
+ *
+ * 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;
+    /** Candidate policy for the station's exchange; the default is relay-only. */
+    iceTransportPolicy?: "relay" | "all";
+    /**
+     * The remote streams its video as RTP on the offer's video m-line and serves no data channel: the
+     * offer's application section is rejected and the video track's packets are emitted as `rtp`.
+     */
+    mediaTrack?: boolean;
+    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];
+    /** The hub echoed the portal keepalive on the command channel. */
+    keepaliveEcho: [];
+    /** One RTP (or multiplexed RTCP) packet from the offer's video m-line, in a {@link RtcPeerOptions.mediaTrack} peer. */
+    rtp: [packet: Buffer];
+    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 remoteMid;
+    private handlingOffer;
+    private channelsCreated;
+    private videoMid?;
+    private videoTrack?;
+    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. A
+     * {@link RtcPeerOptions.mediaTrack} peer applies the offer with its application section rejected,
+     * declares no channels, and adds remote candidates on the offer's first (bundle-tagged) mid.
+     */
+    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.
+     */
+    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. The hub's echo of the portal
+     * keepalive on the command channel is unframed and surfaces as `keepaliveEcho` instead.
+     */
+    private wireChannel;
+    /** Take the offer's video m-line as the one track whose RTP is emitted; any other track is left alone. */
+    private wireVideoTrack;
+    private addNow;
+    private flushPending;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * The portal's data-channel keepalive for an RTC session.
+ *
+ * {@link PORTAL_KEEPALIVE} is the 36 bytes the portal sends unframed on the data channel — a 20-byte
+ * prefix then a bare `XZYH 1139`, no portal packet header — and the hub echoes it. Sent every
+ * {@link PORTAL_KEEPALIVE_MS}, it stops the hub idling the session out.
+ */
+/** The portal's 36-byte data-channel keepalive: a 20-byte prefix and a bare `XZYH 1139`. */
+export declare const PORTAL_KEEPALIVE: Buffer<ArrayBuffer>;
+/** How often {@link PORTAL_KEEPALIVE} goes out on an RTC session. */
+export declare const PORTAL_KEEPALIVE_MS = 29000;

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

@@ -0,0 +1,72 @@
+/**
+ * The command framing a HomeBase S1 Pro (T9000) speaks over its WebRTC data channel — the wire the
+ * security.eufy.com web client builds, reproduced byte-exact.
+ *
+ * A packet is a 16-byte header behind the ASCII magic `XZYH`, then a JSON body, sent in the clear (the
+ * DTLS channel is the encryption). Replies come back with `isResponse = 1`, the same `segment` the
+ * request carried, and a body whose first four bytes are a little-endian result code.
+ *
+ * Every offset is the portal bundle's header builder and parser (`Gr()` / `Qr()`) and its
+ * `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;
+    paramLength: number;
+    segment: number;
+    channel: number;
+    isResponse: number;
+    devType: number;
+}
+export interface PortalRequest {
+    commandId: number;
+    channel: number;
+    /** 1..255, wraps; echoed by the reply so it can be matched. */
+    segment: number;
+    payload: Record<string, unknown>;
+    isResponse?: number;
+    devType?: number;
+}
+export interface PortalResponse {
+    commandId: number;
+    channel: number;
+    segment: number;
+    isResponse: number;
+    linkType: number;
+    /** Command-channel replies only: the int32 result code (0 = ok). */
+    errCode?: number;
+    /** Notify frames: the nested `cmd` the JSON body carries. */
+    cmd?: number;
+    data?: unknown;
+}
+/** The 16-byte header (portal `Gr()`). */
+export declare function buildPortalHeader(commandId: number, paramLength: number, channel: number, segment: number, isResponse?: number, devType?: number): Buffer;
+/** Parse the header (portal `Qr()`); `undefined` when the magic is missing or the buffer is short. */
+export declare function parsePortalHeader(buf: Buffer): PortalHeader | undefined;
+/** Whether a buffer starts a portal packet. */
+export declare function isPortalPacket(buf: Buffer): boolean;
+/** A complete request packet: header + body. */
+export declare function buildPortalPacket(req: PortalRequest): Buffer;
+/**
+ * Parse an inbound packet. On the command channel the body opens with the int32 result code and may
+ * carry JSON after it; on the notify channel the whole body is JSON with a nested `cmd`.
+ */
+export declare function parsePortalPacket(buf: Buffer, linkType?: number): PortalResponse | undefined;
+/** A 1..255 segment counter that never yields 0 (the portal reserves it). */
+export declare class SegmentCounter {
+    private current;
+    next(): number;
+}

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;
+}