im-rtc-call-engine 1.0.0

package/dist/signaling/discipline.js

@@ -0,0 +1,100 @@
+import { ErrorCode, RtcError } from '../errors.js';
+/**
+ * RTC_PROTOCOL.md §2.4「七条编码硬规则」里能**脱离帧定义**判定的那几条。
+ *
+ * 它们是「三端都能实现」这句话的落点：不放浮点、不放 null、数组同构、嵌套不超过两层，
+ * 于是 C++ 不需要 optional<optional<T>>、TS 不需要区分 undefined 与 null、
+ * Swift 不需要 Optional<Optional>。
+ *
+ * 剩下两条（字段类型恒定、枚举封闭带兜底）没法脱离帧定义判，由 fieldSpec.ts 负责。
+ */
+/** data 本身算第 1 层，再嵌一层算第 2 层，第 3 层非法。数组不增加深度。 */
+const MAX_OBJECT_DEPTH = 2;
+/** 2^53-1：超出这个范围 JS 会**静默**丢精度，那种 bug 在四端联调里基本定位不了。 */
+const MAX_SAFE_PROTOCOL_INT = Number.MAX_SAFE_INTEGER;
+/**
+ * checkDiscipline 检查一个已解析的 data 是否满足编码硬规则。
+ * 违规抛 RtcError（bad_envelope 或 bad_params）。
+ */
+export function checkDiscipline(data) {
+    walk(data, 1, 'data');
+}
+function walk(value, depth, path) {
+    if (value === null) {
+        // §2.4 规则 2：协议里任何位置都不许出现 null。可选字段的表达方式是**省略**。
+        throw new RtcError(ErrorCode.badEnvelope, {
+            cause: new Error(`${path}: 出现 null；可选字段请省略，不要写 null`),
+        });
+    }
+    if (typeof value === 'number') {
+        checkNumber(value, path);
+        return;
+    }
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (Array.isArray(value)) {
+        walkArray(value, depth, path);
+        return;
+    }
+    walkObject(value, depth, path);
+}
+function walkObject(value, depth, path) {
+    if (depth > MAX_OBJECT_DEPTH) {
+        throw new RtcError(ErrorCode.badParams, {
+            cause: new Error(`${path}: 对象嵌套 ${depth} 层 > 上限 ${MAX_OBJECT_DEPTH}；` +
+                '要塞任意结构请用 user_data（opaque 字符串）'),
+        });
+    }
+    for (const [key, child] of Object.entries(value)) {
+        walk(child, depth + 1, `${path}.${key}`);
+    }
+}
+/**
+ * walkArray 除了递归检查元素，还要确认数组是**同构**的（§2.4 规则 4）。
+ * 异构数组在 TS/Swift 里勉强能表达，在 C++ 里就得上 variant——所以协议层直接禁掉。
+ */
+function walkArray(value, depth, path) {
+    let firstKind;
+    for (let i = 0; i < value.length; i += 1) {
+        // noUncheckedIndexedAccess 下这是 JsonValue | undefined；数组内不会有洞，
+        // 但类型系统不知道，所以显式取一次。
+        const element = value[i];
+        const kind = kindOf(element);
+        if (i === 0) {
+            firstKind = kind;
+        }
+        else if (kind !== firstKind) {
+            throw new RtcError(ErrorCode.badParams, {
+                cause: new Error(`${path}: 数组必须同构，第 0 个是 ${String(firstKind)}、第 ${i} 个是 ${kind}；` +
+                    '要成对请用对象数组'),
+            });
+        }
+        walk(element, depth, `${path}[${i}]`);
+    }
+}
+/**
+ * checkNumber 落实 §2.4 规则 1（没有浮点数）与规则 7（整数不超过 2^53-1）。
+ *
+ * 判定按**值**而不是按字面量：`1e3` 是整数 1000，合法；`4.5` 不是，非法。
+ * 四端必须用同一套判定，否则一端发得出去、另一端收不下来。
+ */
+function checkNumber(value, path) {
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+        throw new RtcError(ErrorCode.badParams, {
+            cause: new Error(`${path}: 协议里没有浮点数，得到 ${value}；音量/质量/时长/码率一律用整数`),
+        });
+    }
+    if (Math.abs(value) > MAX_SAFE_PROTOCOL_INT) {
+        throw new RtcError(ErrorCode.badParams, {
+            cause: new Error(`${path}: 整数 ${value} 超出 ±(2^53-1)，会静默丢精度`),
+        });
+    }
+}
+function kindOf(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+//# sourceMappingURL=discipline.js.map

package/dist/signaling/discipline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discipline.js","sourceRoot":"","sources":["../../src/signaling/discipline.ts"],"names":[],"mappings":"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"}

package/dist/signaling/enums.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 协议枚举：**封闭的小写字符串集合**（RTC_PROTOCOL.md §2.4 规则 6）。
+ *
+ * 每个枚举都配一个兜底值，收到集合外的值折成它——这是「新增枚举值不算破坏兼容」
+ * （§10）成立的前提：服务端发一个老客户端不认识的值时，老客户端不能崩。
+ *
+ * 用 `as const` 数组 + 联合类型，不用 TS `enum`（CONVENTIONS §3）。
+ */
+/** MEDIA_TYPES：通话媒体类型。兜底 'audio'——宁可当语音，也不去开一个不存在的摄像头。 */
+export declare const MEDIA_TYPES: readonly ["audio", "video"];
+/** MediaType 是 media_type 的取值。 */
+export type MediaType = (typeof MEDIA_TYPES)[number];
+/** REASONS：通话结束原因，与 reasons.ts 的 CallEndReason 同一份。兜底 'error'。 */
+export declare const REASONS: readonly ["hangup", "cancel", "reject", "no_answer", "busy", "offline", "answered_elsewhere", "rejected_elsewhere", "kicked", "room_closed", "network", "error"];
+/** LAYERS：simulcast 层。'none' = 暂停下发但保留订阅。兜底 'l'——宁可给小图。 */
+export declare const LAYERS: readonly ["none", "l", "m", "h"];
+/** Layer 是 max_layer 的取值。 */
+export type Layer = (typeof LAYERS)[number];
+/** TRACK_KINDS：Track 类型。 */
+export declare const TRACK_KINDS: readonly ["audio", "video"];
+/** TrackKind 是 kind 的取值。 */
+export type TrackKind = (typeof TRACK_KINDS)[number];
+/** TRACK_SOURCES：Track 来源。同一 participant 同一 source 最多一条 Track。 */
+export declare const TRACK_SOURCES: readonly ["microphone", "camera", "screen", "screen_audio"];
+/** TrackSource 是 source 的取值。 */
+export type TrackSource = (typeof TRACK_SOURCES)[number];
+/**
+ * PC_ROLES：两条 PeerConnection。**每条的 offerer 是固定的**（§3.3）——
+ * pub 由客户端 offer、sub 由服务端 offer。固定 offerer 就没有 glare，
+ * 所以 engine 里不需要 perfect negotiation / rollback。
+ */
+export declare const PC_ROLES: readonly ["pub", "sub"];
+/** PcRole 是 pc 的取值。 */
+export type PcRole = (typeof PC_ROLES)[number];
+/** ROOM_KINDS：房间策略预设。 */
+export declare const ROOM_KINDS: readonly ["call_1v1", "call_group", "meeting"];
+/** RoomKind 是 room_kind 的取值。 */
+export type RoomKind = (typeof ROOM_KINDS)[number];
+/** HANDLED_ACTIONS：另一台设备做了什么。 */
+export declare const HANDLED_ACTIONS: readonly ["accept", "reject"];
+/** HandledAction 是 action 的取值。 */
+export type HandledAction = (typeof HANDLED_ACTIONS)[number];
+/** 网络质量等级 0~6（§3.4）。0 是 unknown，也是越界值的兜底。 */
+export declare const QUALITY_UNKNOWN = 0;
+/** QUALITY_DISCONNECTED 是 level 的上界。 */
+export declare const QUALITY_DISCONNECTED = 6;
+/** 振铃超时的默认值与范围（§2.6）。越界钳到边界，不报错。 */
+export declare const DEFAULT_TIMEOUT_SEC = 30;
+/** MIN_TIMEOUT_SEC 是振铃超时下界。 */
+export declare const MIN_TIMEOUT_SEC = 5;
+/** MAX_TIMEOUT_SEC 是振铃超时上界。 */
+export declare const MAX_TIMEOUT_SEC = 120;
+//# sourceMappingURL=enums.d.ts.map

package/dist/signaling/enums.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../src/signaling/enums.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,0DAA0D;AAC1D,eAAO,MAAM,WAAW,6BAA8B,CAAC;AACvD,kCAAkC;AAClC,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,kEAAkE;AAClE,eAAO,MAAM,OAAO,kKAaV,CAAC;AAEX,2DAA2D;AAC3D,eAAO,MAAM,MAAM,kCAAmC,CAAC;AACvD,6BAA6B;AAC7B,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5C,4BAA4B;AAC5B,eAAO,MAAM,WAAW,6BAA8B,CAAC;AACvD,4BAA4B;AAC5B,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,kEAAkE;AAClE,eAAO,MAAM,aAAa,6DAA8D,CAAC;AACzF,gCAAgC;AAChC,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,QAAQ,yBAA0B,CAAC;AAChD,uBAAuB;AACvB,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/C,yBAAyB;AACzB,eAAO,MAAM,UAAU,gDAAiD,CAAC;AACzE,gCAAgC;AAChC,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,iCAAiC;AACjC,eAAO,MAAM,eAAe,+BAAgC,CAAC;AAC7D,kCAAkC;AAClC,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,6CAA6C;AAC7C,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,wCAAwC;AACxC,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,oCAAoC;AACpC,eAAO,MAAM,mBAAmB,KAAK,CAAC;AACtC,+BAA+B;AAC/B,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,+BAA+B;AAC/B,eAAO,MAAM,eAAe,MAAM,CAAC"}

package/dist/signaling/enums.js

@@ -0,0 +1,52 @@
+/**
+ * 协议枚举：**封闭的小写字符串集合**（RTC_PROTOCOL.md §2.4 规则 6）。
+ *
+ * 每个枚举都配一个兜底值，收到集合外的值折成它——这是「新增枚举值不算破坏兼容」
+ * （§10）成立的前提：服务端发一个老客户端不认识的值时，老客户端不能崩。
+ *
+ * 用 `as const` 数组 + 联合类型，不用 TS `enum`（CONVENTIONS §3）。
+ */
+/** MEDIA_TYPES：通话媒体类型。兜底 'audio'——宁可当语音，也不去开一个不存在的摄像头。 */
+export const MEDIA_TYPES = ['audio', 'video'];
+/** REASONS：通话结束原因，与 reasons.ts 的 CallEndReason 同一份。兜底 'error'。 */
+export const REASONS = [
+    'hangup',
+    'cancel',
+    'reject',
+    'no_answer',
+    'busy',
+    'offline',
+    'answered_elsewhere',
+    'rejected_elsewhere',
+    'kicked',
+    'room_closed',
+    'network',
+    'error',
+];
+/** LAYERS：simulcast 层。'none' = 暂停下发但保留订阅。兜底 'l'——宁可给小图。 */
+export const LAYERS = ['none', 'l', 'm', 'h'];
+/** TRACK_KINDS：Track 类型。 */
+export const TRACK_KINDS = ['audio', 'video'];
+/** TRACK_SOURCES：Track 来源。同一 participant 同一 source 最多一条 Track。 */
+export const TRACK_SOURCES = ['microphone', 'camera', 'screen', 'screen_audio'];
+/**
+ * PC_ROLES：两条 PeerConnection。**每条的 offerer 是固定的**（§3.3）——
+ * pub 由客户端 offer、sub 由服务端 offer。固定 offerer 就没有 glare，
+ * 所以 engine 里不需要 perfect negotiation / rollback。
+ */
+export const PC_ROLES = ['pub', 'sub'];
+/** ROOM_KINDS：房间策略预设。 */
+export const ROOM_KINDS = ['call_1v1', 'call_group', 'meeting'];
+/** HANDLED_ACTIONS：另一台设备做了什么。 */
+export const HANDLED_ACTIONS = ['accept', 'reject'];
+/** 网络质量等级 0~6（§3.4）。0 是 unknown，也是越界值的兜底。 */
+export const QUALITY_UNKNOWN = 0;
+/** QUALITY_DISCONNECTED 是 level 的上界。 */
+export const QUALITY_DISCONNECTED = 6;
+/** 振铃超时的默认值与范围（§2.6）。越界钳到边界，不报错。 */
+export const DEFAULT_TIMEOUT_SEC = 30;
+/** MIN_TIMEOUT_SEC 是振铃超时下界。 */
+export const MIN_TIMEOUT_SEC = 5;
+/** MAX_TIMEOUT_SEC 是振铃超时上界。 */
+export const MAX_TIMEOUT_SEC = 120;
+//# sourceMappingURL=enums.js.map

package/dist/signaling/enums.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enums.js","sourceRoot":"","sources":["../../src/signaling/enums.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,0DAA0D;AAC1D,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,OAAO,CAAU,CAAC;AAIvD,kEAAkE;AAClE,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,WAAW;IACX,MAAM;IACN,SAAS;IACT,oBAAoB;IACpB,oBAAoB;IACpB,QAAQ;IACR,aAAa;IACb,SAAS;IACT,OAAO;CACC,CAAC;AAEX,2DAA2D;AAC3D,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAU,CAAC;AAIvD,4BAA4B;AAC5B,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,OAAO,CAAU,CAAC;AAIvD,kEAAkE;AAClE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,CAAU,CAAC;AAIzF;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,KAAK,CAAU,CAAC;AAIhD,yBAAyB;AACzB,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,UAAU,EAAE,YAAY,EAAE,SAAS,CAAU,CAAC;AAIzE,iCAAiC;AACjC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAI7D,6CAA6C;AAC7C,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AACjC,wCAAwC;AACxC,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC,oCAAoC;AACpC,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AACtC,+BAA+B;AAC/B,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AACjC,+BAA+B;AAC/B,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC"}

package/dist/signaling/envelope.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 信封：**每一帧都是一个 JSON 对象，四个字段，一个不多一个不少**
+ * （RTC_PROTOCOL.md §2.1）。
+ */
+/** MAX_FRAME_BYTES 是单帧上限（§2.6）。超限对应 WS 关闭码 4400。 */
+export declare const MAX_FRAME_BYTES: number;
+/** OK_SUFFIX 是成功应答的唯一后缀（§2.2）。 */
+export declare const OK_SUFFIX = ".ok";
+/** okType 返回某个请求帧对应的成功应答类型。 */
+export declare function okType(requestType: string): string;
+/** Envelope 是解析后的信封。字段名在 TS 侧用 camelCase，线路上是 snake_case。 */
+export interface Envelope {
+    readonly type: string;
+    /** 服务端主动推送的事件恒为 ''（§2.2）。 */
+    readonly reqId: string;
+    /** 发送方的 Unix 毫秒时间戳。**只用于日志，禁止参与逻辑判断**（时钟偏移）。 */
+    readonly ts: number;
+    readonly data: Readonly<Record<string, unknown>>;
+}
+/**
+ * decodeEnvelope 把一帧原始文本解成 Envelope，并施加 §2.4 的编码硬规则。
+ *
+ * 它**不做**帧级解析——那是 decodeFrame 的事。分成两步是因为路由阶段
+ * 只需要 type 与 req_id，没必要为一个马上要丢掉的帧去解 data。
+ */
+export declare function decodeEnvelope(raw: string): Envelope;
+/** encodeEnvelope 序列化一帧。data 省略时写成 {}。 */
+export declare function encodeEnvelope(type: string, reqId: string, data?: Readonly<Record<string, unknown>>, ts?: number): string;
+/** isEvent 报告这一帧是不是服务端主动推送的事件。 */
+export declare function isEvent(envelope: Envelope): boolean;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/signaling/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/signaling/envelope.ts"],"names":[],"mappings":"AAIA;;;GAGG;AAEH,oDAAoD;AACpD,eAAO,MAAM,eAAe,QAAY,CAAC;AAEzC,kCAAkC;AAClC,eAAO,MAAM,SAAS,QAAQ,CAAC;AAE/B,+BAA+B;AAC/B,wBAAgB,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,6DAA6D;AAC7D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAClD;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAqCpD;AAED,0CAA0C;AAC1C,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM,EAC5C,EAAE,GAAE,MAAmB,GACtB,MAAM,CASR;AAED,kCAAkC;AAClC,wBAAgB,OAAO,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAEnD"}

package/dist/signaling/envelope.js

@@ -0,0 +1,91 @@
+import { byteLength } from '../bytes.js';
+import { ErrorCode, RtcError } from '../errors.js';
+import { checkDiscipline } from './discipline.js';
+/**
+ * 信封：**每一帧都是一个 JSON 对象，四个字段，一个不多一个不少**
+ * （RTC_PROTOCOL.md §2.1）。
+ */
+/** MAX_FRAME_BYTES 是单帧上限（§2.6）。超限对应 WS 关闭码 4400。 */
+export const MAX_FRAME_BYTES = 64 * 1024;
+/** OK_SUFFIX 是成功应答的唯一后缀（§2.2）。 */
+export const OK_SUFFIX = '.ok';
+/** okType 返回某个请求帧对应的成功应答类型。 */
+export function okType(requestType) {
+    return requestType + OK_SUFFIX;
+}
+const REQUIRED_KEYS = ['type', 'req_id', 'ts', 'data'];
+/**
+ * decodeEnvelope 把一帧原始文本解成 Envelope，并施加 §2.4 的编码硬规则。
+ *
+ * 它**不做**帧级解析——那是 decodeFrame 的事。分成两步是因为路由阶段
+ * 只需要 type 与 req_id，没必要为一个马上要丢掉的帧去解 data。
+ */
+export function decodeEnvelope(raw) {
+    if (byteLength(raw) > MAX_FRAME_BYTES) {
+        throw new RtcError(ErrorCode.frameTooLarge, {
+            cause: new Error(`帧 ${byteLength(raw)} 字节 > 上限 ${MAX_FRAME_BYTES}`),
+        });
+    }
+    const parsed = parseObject(raw);
+    for (const key of REQUIRED_KEYS) {
+        if (!Object.hasOwn(parsed, key)) {
+            throw badEnvelope(`缺少必填字段 "${key}"`);
+        }
+    }
+    const type = parsed['type'];
+    if (typeof type !== 'string' || type === '') {
+        throw badEnvelope('字段 type 必须是非空字符串');
+    }
+    const reqId = parsed['req_id'];
+    if (typeof reqId !== 'string') {
+        // req_id 允许是 ''（事件就是 ''），但不允许缺失或非字符串。
+        throw badEnvelope('字段 req_id 必须是字符串');
+    }
+    const ts = parsed['ts'];
+    if (typeof ts !== 'number' || !Number.isInteger(ts)) {
+        throw badEnvelope('字段 ts 必须是整数');
+    }
+    const data = parsed['data'];
+    if (data === null) {
+        throw badEnvelope('字段 data 不能是 null，无内容时用 {}');
+    }
+    if (typeof data !== 'object' || Array.isArray(data)) {
+        throw badEnvelope('字段 data 必须是对象，无内容时用 {}');
+    }
+    checkDiscipline(data);
+    return { type, reqId, ts, data: data };
+}
+/** encodeEnvelope 序列化一帧。data 省略时写成 {}。 */
+export function encodeEnvelope(type, reqId, data = {}, ts = Date.now()) {
+    if (type === '')
+        throw badEnvelope('type 不能为空');
+    const raw = JSON.stringify({ type, req_id: reqId, ts, data });
+    if (byteLength(raw) > MAX_FRAME_BYTES) {
+        throw new RtcError(ErrorCode.frameTooLarge, {
+            cause: new Error(`${type} 编码后 ${byteLength(raw)} 字节 > 上限 ${MAX_FRAME_BYTES}`),
+        });
+    }
+    return raw;
+}
+/** isEvent 报告这一帧是不是服务端主动推送的事件。 */
+export function isEvent(envelope) {
+    return envelope.reqId === '';
+}
+function parseObject(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (cause) {
+        throw new RtcError(ErrorCode.badEnvelope, { cause });
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw badEnvelope('一帧必须是一个 JSON 对象');
+    }
+    // parsed 已确认是非数组的普通对象，这个断言是安全的。
+    return parsed;
+}
+function badEnvelope(reason) {
+    return new RtcError(ErrorCode.badEnvelope, { cause: new Error(reason) });
+}
+//# sourceMappingURL=envelope.js.map

package/dist/signaling/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/signaling/envelope.ts"],"names":[],"mappings":"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"}

package/dist/signaling/fieldSpec.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 帧字段的**声明式定义**：一处声明同时产出运行时校验与 TS 类型。
+ *
+ * 为什么不像服务端那样逐帧写结构体：TS 有条件类型，可以从声明推出类型，
+ * 于是「协议表 → 代码」只需要写一遍。两处写会漂，一处写不会。
+ *
+ * 这套声明负责 RTC_PROTOCOL.md §2.4 里**必须结合帧定义**才能判的两条：
+ * 规则 3（字段类型恒定）与规则 6（枚举封闭且带兜底）。
+ * 与帧无关的四条在 discipline.ts。
+ */
+/** FieldSpec 是一个字段的契约。`wire` 是线路上的 snake_case 名。 */
+export type FieldSpec = {
+    readonly kind: 'string';
+    readonly wire: string;
+    readonly default?: string;
+} | {
+    readonly kind: 'int';
+    readonly wire: string;
+    readonly default?: number;
+    readonly min?: number;
+    readonly max?: number;
+    /**
+     * 越界时的处理方式。协议对不同字段的规定不一样，不能一刀切：
+     * - `timeout_sec` 越界**钳到边界**（§2.6）；
+     * - 质量 `level` 越界**折成 0 = unknown**（§2.4 规则 6 的兜底表）。
+     *
+     * 给了 outOfRange 就折成它，没给就钳到边界。
+     */
+    readonly outOfRange?: number;
+} | {
+    readonly kind: 'bool';
+    readonly wire: string;
+    readonly default?: boolean;
+} | {
+    readonly kind: 'enum';
+    readonly wire: string;
+    readonly values: readonly string[];
+    /** 收到集合外的值时折成它，**禁止崩溃、禁止透传给 UI**。 */
+    readonly fallback: string;
+    readonly default?: string;
+} | {
+    readonly kind: 'stringArray';
+    readonly wire: string;
+} | {
+    readonly kind: 'enumArray';
+    readonly wire: string;
+    readonly values: readonly string[];
+    readonly fallback: string;
+} | {
+    readonly kind: 'objectArray';
+    readonly wire: string;
+    readonly fields: FrameFields;
+} | {
+    readonly kind: 'object';
+    readonly wire: string;
+    readonly fields: FrameFields;
+};
+/** FrameFields 把 camelCase 属性名映射到字段契约。 */
+export type FrameFields = Readonly<Record<string, FieldSpec>>;
+/** FieldType 从字段契约推出 TS 类型。 */
+type FieldType<S extends FieldSpec> = S extends {
+    kind: 'string';
+} ? string : S extends {
+    kind: 'int';
+} ? number : S extends {
+    kind: 'bool';
+} ? boolean : S extends {
+    kind: 'enum';
+    values: readonly (infer V)[];
+} ? V : S extends {
+    kind: 'stringArray';
+} ? string[] : S extends {
+    kind: 'enumArray';
+    values: readonly (infer V)[];
+} ? V[] : S extends {
+    kind: 'objectArray';
+    fields: infer F;
+} ? F extends FrameFields ? FrameData<F>[] : never : S extends {
+    kind: 'object';
+    fields: infer F;
+} ? F extends FrameFields ? FrameData<F> : never : never;
+/**
+ * FrameData 从字段声明推出整帧的 TS 类型。
+ *
+ * `-readonly` 是必要的：字段声明用 `as const` 写，同态映射会把 readonly 一并带过来，
+ * 于是「从 newFrameData() 起手再改字段」这条发送侧规矩就没法执行了。
+ */
+export type FrameData<F extends FrameFields> = {
+    -readonly [K in keyof F]: FieldType<F[K]>;
+};
+/**
+ * decodeFields 把线路上的 data 解成带默认值的帧对象。
+ *
+ * 「可选字段用省略表达，接收方按默认值填」（§2.4 规则 2）就落在这里：
+ * 字段缺席 → 取 spec 的默认值；出现了 → 校验类型、归一化枚举、钳制数值。
+ */
+export declare function decodeFields<F extends FrameFields>(fields: F, raw: Readonly<Record<string, unknown>>, path?: string): FrameData<F>;
+/** encodeFields 把帧对象映射回线路上的 snake_case data。 */
+export declare function encodeFields<F extends FrameFields>(fields: F, value: FrameData<F>): Record<string, unknown>;
+export {};
+//# sourceMappingURL=fieldSpec.d.ts.map

package/dist/signaling/fieldSpec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fieldSpec.d.ts","sourceRoot":"","sources":["../../src/signaling/fieldSpec.ts"],"names":[],"mappings":"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"}

package/dist/signaling/fieldSpec.js

@@ -0,0 +1,130 @@
+import { ErrorCode, RtcError } from '../errors.js';
+/**
+ * decodeFields 把线路上的 data 解成带默认值的帧对象。
+ *
+ * 「可选字段用省略表达，接收方按默认值填」（§2.4 规则 2）就落在这里：
+ * 字段缺席 → 取 spec 的默认值；出现了 → 校验类型、归一化枚举、钳制数值。
+ */
+export function decodeFields(fields, raw, path = 'data') {
+    const out = {};
+    for (const [prop, spec] of Object.entries(fields)) {
+        out[prop] = decodeField(spec, raw[spec.wire], `${path}.${spec.wire}`);
+    }
+    // out 的每个键都按 fields 的声明填过了，这个断言与上面的循环一一对应。
+    return out;
+}
+/** encodeFields 把帧对象映射回线路上的 snake_case data。 */
+export function encodeFields(fields, value) {
+    const out = {};
+    for (const [prop, spec] of Object.entries(fields)) {
+        const own = value[prop];
+        out[spec.wire] = encodeField(spec, own);
+    }
+    return out;
+}
+function decodeField(spec, value, path) {
+    if (value === undefined)
+        return defaultOf(spec);
+    switch (spec.kind) {
+        case 'string':
+            return expectString(value, path);
+        case 'bool':
+            // 布尔必须是真布尔：0/1/"true" 一律拒（§2.4「禁止用 0/1 代替」）。
+            if (typeof value !== 'boolean')
+                throw badParams(`${path} 必须是布尔，得到 ${typeOf(value)}`);
+            return value;
+        case 'int':
+            return coerceInt(expectInt(value, path), spec.min, spec.max, spec.outOfRange);
+        case 'enum':
+            return normalizeEnum(expectString(value, path), spec.values, spec.fallback);
+        case 'stringArray':
+            return expectArray(value, path).map((item, i) => expectString(item, `${path}[${i}]`));
+        case 'enumArray':
+            return expectArray(value, path).map((item, i) => normalizeEnum(expectString(item, `${path}[${i}]`), spec.values, spec.fallback));
+        case 'objectArray':
+            return expectArray(value, path).map((item, i) => decodeFields(spec.fields, expectObject(item, `${path}[${i}]`), `${path}[${i}]`));
+        case 'object':
+            return decodeFields(spec.fields, expectObject(value, path), path);
+    }
+}
+function encodeField(spec, value) {
+    if (value === undefined)
+        return defaultOf(spec);
+    if (spec.kind === 'objectArray') {
+        return expectArray(value, spec.wire).map((item) => encodeFields(spec.fields, item));
+    }
+    if (spec.kind === 'object') {
+        return encodeFields(spec.fields, value);
+    }
+    return value;
+}
+/**
+ * defaultOf 给出字段的协议默认值。
+ *
+ * **数组的默认值恒为空数组，绝不是 null/undefined**——协议里没有 null，
+ * 而 JSON.stringify 会把 undefined 字段整个丢掉，导致「本该有的空数组不见了」。
+ */
+function defaultOf(spec) {
+    switch (spec.kind) {
+        case 'string':
+            return spec.default ?? '';
+        case 'int':
+            return spec.default ?? 0;
+        case 'bool':
+            return spec.default ?? false;
+        case 'enum':
+            return spec.default ?? spec.fallback;
+        case 'stringArray':
+        case 'enumArray':
+        case 'objectArray':
+            return [];
+        case 'object':
+            return decodeFields(spec.fields, {});
+    }
+}
+function normalizeEnum(value, values, fallback) {
+    return values.includes(value) ? value : fallback;
+}
+function coerceInt(value, min, max, outOfRange) {
+    const belowMin = min !== undefined && value < min;
+    const aboveMax = max !== undefined && value > max;
+    if (!belowMin && !aboveMax)
+        return value;
+    if (outOfRange !== undefined)
+        return outOfRange;
+    return belowMin ? min : max;
+}
+function expectString(value, path) {
+    if (typeof value !== 'string')
+        throw badParams(`${path} 必须是字符串，得到 ${typeOf(value)}`);
+    return value;
+}
+function expectInt(value, path) {
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        throw badParams(`${path} 必须是整数，得到 ${typeOf(value)}`);
+    }
+    return value;
+}
+function expectArray(value, path) {
+    if (!Array.isArray(value))
+        throw badParams(`${path} 必须是数组，得到 ${typeOf(value)}`);
+    return value;
+}
+function expectObject(value, path) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw badParams(`${path} 必须是对象，得到 ${typeOf(value)}`);
+    }
+    // 已确认是非数组的普通对象。
+    return value;
+}
+function typeOf(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+function badParams(reason) {
+    return new RtcError(ErrorCode.badParams, { cause: new Error(reason) });
+}
+//# sourceMappingURL=fieldSpec.js.map

package/dist/signaling/fieldSpec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fieldSpec.js","sourceRoot":"","sources":["../../src/signaling/fieldSpec.ts"],"names":[],"mappings":"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"}

package/dist/signaling/frameSender.d.ts

@@ -0,0 +1,34 @@
+import type { MediaAdapter } from '../media/mediaAdapter.js';
+import type { Connection } from './connection.js';
+import type { PcRole } from './enums.js';
+/**
+ * FrameSender 把状态机产出的**意图**变成线路上的一帧。
+ *
+ * # 为什么这一层要单独存在
+ *
+ * 状态机是纯函数，产不出 SDP——它给的协商帧 `sdp` 字段是空的。
+ * 「取真值填进去」这件事既要碰媒体层又要碰连接，放在状态机里会毁掉它的可测性，
+ * 放在门面里则让门面同时管路由、填 SDP 和事件三件事。所以单独一层：
+ * **门面只管把帧交给它，它只管把帧变成真的**。
+ */
+export declare class FrameSender {
+    private readonly media;
+    /** 服务端最近一次下发的 sub offer，答复时要用。 */
+    private lastSubOfferSdp;
+    constructor(media: MediaAdapter);
+    /** noteSubOffer 记下服务端下发的 sub offer。**答复它时才有得可答**。 */
+    noteSubOffer(sdp: string): void;
+    /**
+     * send 发一帧并返回应答（`{type, data}`）。
+     *
+     * 返回应答而不是直接消化掉：**`.ok` 也要喂回状态机**——join.ok / publish.ok
+     * 都是状态推进的关键一步，漏掉那一半会让房间永远停在 `joining`。
+     */
+    send(connection: Connection, type: string, data: Readonly<Record<string, unknown>>): Promise<{
+        type: string;
+        data: Record<string, unknown>;
+    } | null>;
+    /** sendCandidate 发一个本端候选。候选是尽力而为的，失败由调用方转成 error 事件。 */
+    sendCandidate(connection: Connection, pc: PcRole, candidate: RTCIceCandidateInit): Promise<void>;
+}
+//# sourceMappingURL=frameSender.d.ts.map

package/dist/signaling/frameSender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frameSender.d.ts","sourceRoot":"","sources":["../../src/signaling/frameSender.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC;;;;;;;;;GASG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,kCAAkC;IAClC,OAAO,CAAC,eAAe,CAAM;gBAEjB,KAAK,EAAE,YAAY;IAI/B,qDAAqD;IACrD,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI/B;;;;;OAKG;IACG,IAAI,CACR,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACtC,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IAclE,wDAAwD;IAClD,aAAa,CACjB,UAAU,EAAE,UAAU,EACtB,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,mBAAmB,GAC7B,OAAO,CAAC,IAAI,CAAC;CAUjB"}