im-rtc-call-engine 1.0.0

package/dist/reasons.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 通话结束原因：**一套 reason，三处共用**——`call.ended` 帧、`onCallEnd` 事件、
+ * 服务端 webhook。单一真相源是 `im-rtc-server/docs/conformance/reasons.json`
+ * （由 RTC_PROTOCOL.md §6 定稿）。
+ */
+/** CallEndReason 是通话结束原因的封闭集合。 */
+export declare const CallEndReason: {
+    /** 已接通成员主动挂断。时长 > 0。 */
+    readonly hangup: "hangup";
+    /** 主叫在接通前取消。 */
+    readonly cancel: "cancel";
+    /** 被叫主动拒接。 */
+    readonly reject: "reject";
+    /** 服务端振铃超时。 */
+    readonly noAnswer: "no_answer";
+    /** 被叫已在别的通话中。 */
+    readonly busy: "busy";
+    /** 被叫无在线设备。 */
+    readonly offline: "offline";
+    /** 本账号另一台设备接听了。 */
+    readonly answeredElsewhere: "answered_elsewhere";
+    /** 本账号另一台设备拒绝了。 */
+    readonly rejectedElsewhere: "rejected_elsewhere";
+    /** 被主持人或管理 API 移出。 */
+    readonly kicked: "kicked";
+    /** 房间被强制解散。 */
+    readonly roomClosed: "room_closed";
+    /** 掉线超过 30 秒恢复窗口。 */
+    readonly network: "network";
+    /** 服务端内部错误兜底，**也是未知值的兜底**。 */
+    readonly error: "error";
+};
+/** CallEndReasonValue 是 reason 的取值联合。 */
+export type CallEndReasonValue = (typeof CallEndReason)[keyof typeof CallEndReason];
+/**
+ * normalizeReason 把陌生的 reason 折成 'error'。
+ *
+ * 这条兜底是 RTC_PROTOCOL.md §10「新增枚举值不算破坏兼容」成立的前提：
+ * 服务端发一个老客户端不认识的 reason 时，老客户端**必须**不崩、不把原始字符串
+ * 显示给用户。
+ */
+export declare function normalizeReason(value: unknown): CallEndReasonValue;
+/**
+ * GROUP_DOMINANT_PRIORITY 是群通话「全员都没接听时取哪个 reason」的固定优先级
+ * （RTC_PROTOCOL.md §4.4 规则 3）。
+ *
+ * 定成有序表而不是散落的 if，是为了**四端算出同一个值**。
+ */
+export declare const GROUP_DOMINANT_PRIORITY: readonly CallEndReasonValue[];
+/**
+ * dominantReason 从一组成员裁决里挑出群通话的主导 reason。
+ * 没有一个落在优先级表里时返回 no_answer——保守地按「没人接」记。
+ */
+export declare function dominantReason(outcomes: readonly string[]): CallEndReasonValue;
+/**
+ * callDurationSec 按协议算通话时长：未接通恒为 0，接通则向下取整到秒。
+ *
+ * **正常路径下客户端不该自己算**——一律用 `call.ended` 帧里的 `duration_sec`
+ * （时钟偏移）。这个函数只服务一个例外：重连恢复失败时服务端的 ended 帧送不到，
+ * engine 要本地合成 `onCallEnd(network)`（RTC_PROTOCOL.md 不变量 I8）。
+ */
+export declare function callDurationSec(connectedAtMs: number, endedAtMs: number): number;
+//# sourceMappingURL=reasons.d.ts.map

package/dist/reasons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasons.d.ts","sourceRoot":"","sources":["../src/reasons.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,kCAAkC;AAClC,eAAO,MAAM,aAAa;IACxB,wBAAwB;;IAExB,gBAAgB;;IAEhB,cAAc;;IAEd,eAAe;;IAEf,iBAAiB;;IAEjB,eAAe;;IAEf,mBAAmB;;IAEnB,mBAAmB;;IAEnB,sBAAsB;;IAEtB,eAAe;;IAEf,qBAAqB;;IAErB,8BAA8B;;CAEtB,CAAC;AAEX,yCAAyC;AACzC,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAIpF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAIlE;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,kBAAkB,EAKhE,CAAC;AAEF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB,CAK9E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAGhF"}

package/dist/reasons.js

@@ -0,0 +1,81 @@
+/**
+ * 通话结束原因：**一套 reason，三处共用**——`call.ended` 帧、`onCallEnd` 事件、
+ * 服务端 webhook。单一真相源是 `im-rtc-server/docs/conformance/reasons.json`
+ * （由 RTC_PROTOCOL.md §6 定稿）。
+ */
+/** CallEndReason 是通话结束原因的封闭集合。 */
+export const CallEndReason = {
+    /** 已接通成员主动挂断。时长 > 0。 */
+    hangup: 'hangup',
+    /** 主叫在接通前取消。 */
+    cancel: 'cancel',
+    /** 被叫主动拒接。 */
+    reject: 'reject',
+    /** 服务端振铃超时。 */
+    noAnswer: 'no_answer',
+    /** 被叫已在别的通话中。 */
+    busy: 'busy',
+    /** 被叫无在线设备。 */
+    offline: 'offline',
+    /** 本账号另一台设备接听了。 */
+    answeredElsewhere: 'answered_elsewhere',
+    /** 本账号另一台设备拒绝了。 */
+    rejectedElsewhere: 'rejected_elsewhere',
+    /** 被主持人或管理 API 移出。 */
+    kicked: 'kicked',
+    /** 房间被强制解散。 */
+    roomClosed: 'room_closed',
+    /** 掉线超过 30 秒恢复窗口。 */
+    network: 'network',
+    /** 服务端内部错误兜底，**也是未知值的兜底**。 */
+    error: 'error',
+};
+const KNOWN_REASONS = new Set(Object.values(CallEndReason));
+/**
+ * normalizeReason 把陌生的 reason 折成 'error'。
+ *
+ * 这条兜底是 RTC_PROTOCOL.md §10「新增枚举值不算破坏兼容」成立的前提：
+ * 服务端发一个老客户端不认识的 reason 时，老客户端**必须**不崩、不把原始字符串
+ * 显示给用户。
+ */
+export function normalizeReason(value) {
+    return typeof value === 'string' && KNOWN_REASONS.has(value)
+        ? value
+        : CallEndReason.error;
+}
+/**
+ * GROUP_DOMINANT_PRIORITY 是群通话「全员都没接听时取哪个 reason」的固定优先级
+ * （RTC_PROTOCOL.md §4.4 规则 3）。
+ *
+ * 定成有序表而不是散落的 if，是为了**四端算出同一个值**。
+ */
+export const GROUP_DOMINANT_PRIORITY = [
+    CallEndReason.reject,
+    CallEndReason.busy,
+    CallEndReason.noAnswer,
+    CallEndReason.offline,
+];
+/**
+ * dominantReason 从一组成员裁决里挑出群通话的主导 reason。
+ * 没有一个落在优先级表里时返回 no_answer——保守地按「没人接」记。
+ */
+export function dominantReason(outcomes) {
+    for (const candidate of GROUP_DOMINANT_PRIORITY) {
+        if (outcomes.includes(candidate))
+            return candidate;
+    }
+    return CallEndReason.noAnswer;
+}
+/**
+ * callDurationSec 按协议算通话时长：未接通恒为 0，接通则向下取整到秒。
+ *
+ * **正常路径下客户端不该自己算**——一律用 `call.ended` 帧里的 `duration_sec`
+ * （时钟偏移）。这个函数只服务一个例外：重连恢复失败时服务端的 ended 帧送不到，
+ * engine 要本地合成 `onCallEnd(network)`（RTC_PROTOCOL.md 不变量 I8）。
+ */
+export function callDurationSec(connectedAtMs, endedAtMs) {
+    if (connectedAtMs <= 0)
+        return 0;
+    return Math.max(0, Math.floor((endedAtMs - connectedAtMs) / 1000));
+}
+//# sourceMappingURL=reasons.js.map

package/dist/reasons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasons.js","sourceRoot":"","sources":["../src/reasons.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,kCAAkC;AAClC,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,wBAAwB;IACxB,MAAM,EAAE,QAAQ;IAChB,gBAAgB;IAChB,MAAM,EAAE,QAAQ;IAChB,cAAc;IACd,MAAM,EAAE,QAAQ;IAChB,eAAe;IACf,QAAQ,EAAE,WAAW;IACrB,iBAAiB;IACjB,IAAI,EAAE,MAAM;IACZ,eAAe;IACf,OAAO,EAAE,SAAS;IAClB,mBAAmB;IACnB,iBAAiB,EAAE,oBAAoB;IACvC,mBAAmB;IACnB,iBAAiB,EAAE,oBAAoB;IACvC,sBAAsB;IACtB,MAAM,EAAE,QAAQ;IAChB,eAAe;IACf,UAAU,EAAE,aAAa;IACzB,qBAAqB;IACrB,OAAO,EAAE,SAAS;IAClB,8BAA8B;IAC9B,KAAK,EAAE,OAAO;CACN,CAAC;AAKX,MAAM,aAAa,GAAG,IAAI,GAAG,CAAS,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC;QAC1D,CAAC,CAAE,KAA4B;QAC/B,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAkC;IACpE,aAAa,CAAC,MAAM;IACpB,aAAa,CAAC,IAAI;IAClB,aAAa,CAAC,QAAQ;IACtB,aAAa,CAAC,OAAO;CACtB,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,QAA2B;IACxD,KAAK,MAAM,SAAS,IAAI,uBAAuB,EAAE,CAAC;QAChD,IAAI,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;IACrD,CAAC;IACD,OAAO,aAAa,CAAC,QAAQ,CAAC;AAChC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,aAAqB,EAAE,SAAiB;IACtE,IAAI,aAAa,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACjC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,GAAG,aAAa,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AACrE,CAAC"}

package/dist/redact.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 脱敏：与服务端 `internal/observability` 的 Redact* 系列**行为一致**。
+ *
+ * 为什么 SDP 也算敏感：它带 ICE 候选（暴露内网拓扑与公网地址）、DTLS 指纹、
+ * 以及 SRTP 的密钥协商材料。整条打进日志等于把一次通话的传输面摊开。
+ * 要看完整 SDP 请用 Chrome 的 `webrtc-internals`，不要靠日志。
+ */
+/** redact 把凭据折成「前 6 位 + 长度」。token / roomToken 进日志前必须过它。 */
+export declare function redact(secret: string | undefined | null): string;
+/** redactSdp 把 SDP 折成「行数 + m= 行摘要」，够判断协商的是音频还是视频。 */
+export declare function redactSdp(sdp: string | undefined | null): string;
+/**
+ * redactCandidate 把 ICE 候选折成「传输协议/类型」，不带地址与端口。
+ *
+ * 排查连通性看的是**候选类型分布**（host/srflx/relay）与最终选中的那一对，
+ * 不是每条候选的地址。
+ */
+export declare function redactCandidate(candidate: string | undefined | null): string;
+//# sourceMappingURL=redact.d.ts.map

package/dist/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,2DAA2D;AAC3D,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAIhE;AAED,qDAAqD;AACrD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAOhE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAa5E"}

package/dist/redact.js

@@ -0,0 +1,50 @@
+/**
+ * 脱敏：与服务端 `internal/observability` 的 Redact* 系列**行为一致**。
+ *
+ * 为什么 SDP 也算敏感：它带 ICE 候选（暴露内网拓扑与公网地址）、DTLS 指纹、
+ * 以及 SRTP 的密钥协商材料。整条打进日志等于把一次通话的传输面摊开。
+ * 要看完整 SDP 请用 Chrome 的 `webrtc-internals`，不要靠日志。
+ */
+/** 凭据保留的前缀长度。6 位够在日志里比对「是不是同一枚票」，又不足以伪造。 */
+const REDACT_PREFIX_LEN = 6;
+/** redact 把凭据折成「前 6 位 + 长度」。token / roomToken 进日志前必须过它。 */
+export function redact(secret) {
+    if (secret === undefined || secret === null || secret === '')
+        return '(empty)';
+    if (secret.length <= REDACT_PREFIX_LEN)
+        return `(len=${secret.length})`;
+    return `${secret.slice(0, REDACT_PREFIX_LEN)}…(len=${secret.length})`;
+}
+/** redactSdp 把 SDP 折成「行数 + m= 行摘要」，够判断协商的是音频还是视频。 */
+export function redactSdp(sdp) {
+    if (sdp === undefined || sdp === null || sdp === '')
+        return '(empty)';
+    const lines = sdp.split('\n');
+    const media = lines
+        .filter((line) => line.startsWith('m='))
+        .map((line) => line.trim().split(/\s+/)[0] ?? '');
+    return `sdp(lines=${lines.length}, ${media.join(',')})`;
+}
+/**
+ * redactCandidate 把 ICE 候选折成「传输协议/类型」，不带地址与端口。
+ *
+ * 排查连通性看的是**候选类型分布**（host/srflx/relay）与最终选中的那一对，
+ * 不是每条候选的地址。
+ */
+export function redactCandidate(candidate) {
+    if (candidate === undefined || candidate === null || candidate === '') {
+        return '(end-of-candidates)';
+    }
+    const fields = candidate.split(/\s+/);
+    let transport = '?';
+    let type = '?';
+    fields.forEach((field, i) => {
+        const lower = field.toLowerCase();
+        if (lower === 'udp' || lower === 'tcp')
+            transport = lower;
+        if (lower === 'typ')
+            type = fields[i + 1] ?? '?';
+    });
+    return `candidate(${transport}/${type})`;
+}
+//# sourceMappingURL=redact.js.map

package/dist/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,4CAA4C;AAC5C,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAE5B,2DAA2D;AAC3D,MAAM,UAAU,MAAM,CAAC,MAAiC;IACtD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAC/E,IAAI,MAAM,CAAC,MAAM,IAAI,iBAAiB;QAAE,OAAO,QAAQ,MAAM,CAAC,MAAM,GAAG,CAAC;IACxE,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,SAAS,MAAM,CAAC,MAAM,GAAG,CAAC;AACxE,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,SAAS,CAAC,GAA8B;IACtD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IACtE,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAG,KAAK;SAChB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;SACvC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACpD,OAAO,aAAa,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAC1D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,SAAoC;IAClE,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QACtE,OAAO,qBAAqB,CAAC;IAC/B,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACtC,IAAI,SAAS,GAAG,GAAG,CAAC;IACpB,IAAI,IAAI,GAAG,GAAG,CAAC;IACf,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC1B,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;QAClC,IAAI,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,KAAK;YAAE,SAAS,GAAG,KAAK,CAAC;QAC1D,IAAI,KAAK,KAAK,KAAK;YAAE,IAAI,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC;IACnD,CAAC,CAAC,CAAC;IACH,OAAO,aAAa,SAAS,IAAI,IAAI,GAAG,CAAC;AAC3C,CAAC"}

package/dist/signaling/backoff.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 重连退避：**三端同一份档位**（RTC_PROTOCOL.md §1.4）。
+ *
+ * 档位写死成表而不是算指数，是为了四端一眼能对上；抖动是为了避免
+ * 「服务端重启后所有客户端在同一毫秒回来」把它再打挂一次。
+ */
+/** BACKOFF_STEPS_MS 是退避档位，之后固定用最后一档。 */
+export declare const BACKOFF_STEPS_MS: readonly number[];
+/** JITTER_RATIO 是抖动幅度：每档 ±20%。 */
+export declare const JITTER_RATIO = 0.2;
+/**
+ * backoffDelayMs 返回第 attempt 次重连该等多久（attempt 从 0 开始）。
+ *
+ * `random` 可注入以便测试；默认 Math.random。
+ */
+export declare function backoffDelayMs(attempt: number, random?: () => number): number;
+//# sourceMappingURL=backoff.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../src/signaling/backoff.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wCAAwC;AACxC,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAAiD,CAAC;AAEhG,kCAAkC;AAClC,eAAO,MAAM,YAAY,MAAM,CAAC;AAEhC;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,MAAoB,GAAG,MAAM,CAM1F"}

package/dist/signaling/backoff.js

@@ -0,0 +1,23 @@
+/**
+ * 重连退避：**三端同一份档位**（RTC_PROTOCOL.md §1.4）。
+ *
+ * 档位写死成表而不是算指数，是为了四端一眼能对上；抖动是为了避免
+ * 「服务端重启后所有客户端在同一毫秒回来」把它再打挂一次。
+ */
+/** BACKOFF_STEPS_MS 是退避档位，之后固定用最后一档。 */
+export const BACKOFF_STEPS_MS = [1_000, 2_000, 4_000, 8_000, 15_000, 30_000];
+/** JITTER_RATIO 是抖动幅度：每档 ±20%。 */
+export const JITTER_RATIO = 0.2;
+/**
+ * backoffDelayMs 返回第 attempt 次重连该等多久（attempt 从 0 开始）。
+ *
+ * `random` 可注入以便测试；默认 Math.random。
+ */
+export function backoffDelayMs(attempt, random = Math.random) {
+    const index = Math.min(Math.max(attempt, 0), BACKOFF_STEPS_MS.length - 1);
+    // 上面的 clamp 保证 index 落在数组范围内，这个断言与它一一对应。
+    const base = BACKOFF_STEPS_MS[index];
+    const jitter = base * JITTER_RATIO * (random() * 2 - 1);
+    return Math.max(0, Math.round(base + jitter));
+}
+//# sourceMappingURL=backoff.js.map

package/dist/signaling/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../../src/signaling/backoff.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wCAAwC;AACxC,MAAM,CAAC,MAAM,gBAAgB,GAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAEhG,kCAAkC;AAClC,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC;AAEhC;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,SAAuB,IAAI,CAAC,MAAM;IAChF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC1E,yCAAyC;IACzC,MAAM,IAAI,GAAG,gBAAgB,CAAC,KAAK,CAAW,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,GAAG,YAAY,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACxD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC;AAChD,CAAC"}

package/dist/signaling/candidate.d.ts

@@ -0,0 +1,19 @@
+import type { PcRole } from './enums.js';
+/**
+ * 把线路上的 `room.ice_candidate` data 解析成浏览器要的 `RTCIceCandidateInit`。
+ *
+ * 抽成纯函数不只是为了门面的体量：它有两条容易写错的规则，值得直接单测——
+ * 而门面上的方法只能靠端到端间接覆盖。
+ */
+export interface ParsedCandidate {
+    readonly pc: PcRole;
+    readonly init: RTCIceCandidateInit;
+}
+/**
+ * parseCandidate 解析一条候选；返回 `null` 表示**不需要加**。
+ *
+ * `candidate` 为空串是「收集结束」的信号（协议 §3.3），接收方必须容忍——
+ * 把它当成一条真候选喂给 `addIceCandidate` 在部分浏览器上会抛。
+ */
+export declare function parseCandidate(data: Readonly<Record<string, unknown>>): ParsedCandidate | null;
+//# sourceMappingURL=candidate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"candidate.d.ts","sourceRoot":"","sources":["../../src/signaling/candidate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,eAAe,GAAG,IAAI,CAc9F"}

package/dist/signaling/candidate.js

@@ -0,0 +1,22 @@
+/**
+ * parseCandidate 解析一条候选；返回 `null` 表示**不需要加**。
+ *
+ * `candidate` 为空串是「收集结束」的信号（协议 §3.3），接收方必须容忍——
+ * 把它当成一条真候选喂给 `addIceCandidate` 在部分浏览器上会抛。
+ */
+export function parseCandidate(data) {
+    const candidate = typeof data['candidate'] === 'string' ? data['candidate'] : '';
+    if (candidate === '')
+        return null;
+    const rawIndex = data['sdp_mline_index'];
+    return {
+        // 只有两条 PC；认不出来的一律当 sub——下行才是候选真正要紧的方向。
+        pc: data['pc'] === 'pub' ? 'pub' : 'sub',
+        init: {
+            candidate,
+            sdpMid: typeof data['sdp_mid'] === 'string' ? data['sdp_mid'] : '',
+            sdpMLineIndex: typeof rawIndex === 'number' ? rawIndex : 0,
+        },
+    };
+}
+//# sourceMappingURL=candidate.js.map

package/dist/signaling/candidate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate.js","sourceRoot":"","sources":["../../src/signaling/candidate.ts"],"names":[],"mappings":"AAaA;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAuC;IACpE,MAAM,SAAS,GAAG,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACjF,IAAI,SAAS,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAElC,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC;IACzC,OAAO;QACL,uCAAuC;QACvC,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK;QACxC,IAAI,EAAE;YACJ,SAAS;YACT,MAAM,EAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE;YAClE,aAAa,EAAE,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;SAC3D;KACF,CAAC;AACJ,CAAC"}

package/dist/signaling/caseMapping.d.ts

@@ -0,0 +1,19 @@
+import type { FrameFields } from './fieldSpec.js';
+/**
+ * 线路的 snake_case 与 TS 惯用的 camelCase 之间的两个方向。
+ *
+ * 抽成独立模块不只是为了 engine.ts 的体量：这两个函数是**纯的**，
+ * 值得直接单测，而门面上的方法只能靠端到端间接覆盖。
+ */
+/** snakeToCamel 把 `media_type` 变成 `mediaType`。 */
+export declare function snakeToCamel(key: string): string;
+/** camelizeArgs 把状态机产出的 snake_case 参数整体转成 camelCase。 */
+export declare function camelizeArgs(args: Readonly<Record<string, unknown>>): Record<string, unknown>;
+/**
+ * toFrameProps 把线路形状的 data 转成字段声明用的属性名。
+ *
+ * 两种键都认：状态机产出的是线路名（`track_id`），而调用方手写时更可能用属性名。
+ * **认两种不是含糊**——字段声明里 `wire` 与属性名是一对一的，转换没有歧义。
+ */
+export declare function toFrameProps(fields: FrameFields, data: Readonly<Record<string, unknown>>): Record<string, unknown>;
+//# sourceMappingURL=caseMapping.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"caseMapping.d.ts","sourceRoot":"","sources":["../../src/signaling/caseMapping.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD;;;;;GAKG;AAEH,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAI7F;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACtC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB"}

package/dist/signaling/caseMapping.js

@@ -0,0 +1,34 @@
+/**
+ * 线路的 snake_case 与 TS 惯用的 camelCase 之间的两个方向。
+ *
+ * 抽成独立模块不只是为了 engine.ts 的体量：这两个函数是**纯的**，
+ * 值得直接单测，而门面上的方法只能靠端到端间接覆盖。
+ */
+/** snakeToCamel 把 `media_type` 变成 `mediaType`。 */
+export function snakeToCamel(key) {
+    return key.replace(/_([a-z])/g, (_, ch) => ch.toUpperCase());
+}
+/** camelizeArgs 把状态机产出的 snake_case 参数整体转成 camelCase。 */
+export function camelizeArgs(args) {
+    const out = {};
+    for (const [key, value] of Object.entries(args))
+        out[snakeToCamel(key)] = value;
+    return out;
+}
+/**
+ * toFrameProps 把线路形状的 data 转成字段声明用的属性名。
+ *
+ * 两种键都认：状态机产出的是线路名（`track_id`），而调用方手写时更可能用属性名。
+ * **认两种不是含糊**——字段声明里 `wire` 与属性名是一对一的，转换没有歧义。
+ */
+export function toFrameProps(fields, data) {
+    const out = {};
+    for (const [prop, spec] of Object.entries(fields)) {
+        if (Object.hasOwn(data, spec.wire))
+            out[prop] = data[spec.wire];
+        else if (Object.hasOwn(data, prop))
+            out[prop] = data[prop];
+    }
+    return out;
+}
+//# sourceMappingURL=caseMapping.js.map

package/dist/signaling/caseMapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caseMapping.js","sourceRoot":"","sources":["../../src/signaling/caseMapping.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,kDAAkD;AAClD,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAU,EAAE,EAAE,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AACvE,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,YAAY,CAAC,IAAuC;IAClE,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC;IAChF,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAmB,EACnB,IAAuC;IAEvC,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;aAC3D,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/signaling/connection.d.ts

@@ -0,0 +1,110 @@
+import type { Envelope } from './envelope.js';
+import type { FrameFields } from './fieldSpec.js';
+import type { ConnectionOptions, ConnectionState, HelloOk } from './connectionTypes.js';
+/**
+ * 信令连接：握手、心跳、请求应答配对、退避重连。
+ *
+ * # 为什么按 req_id 配对而不是按帧类型
+ *
+ * pub 侧的 `room.offer` 是由 **`room.answer`** 应答的（协议 §3.3 固定 offerer），
+ * 只看类型对不上号。按 req_id 配对还顺带解决了「多个同类请求在途」的问题。
+ */
+export type { ConnectionState, HelloOk, KickedOutReason, ConnectionEvents, ConnectionOptions, } from './connectionTypes.js';
+/** Connection 是一条信令连接。断线会自动重连，除非关闭码明说不该重连。 */
+export declare class Connection {
+    private readonly options;
+    private ws;
+    private state;
+    private sessionId;
+    private seq;
+    private readonly pending;
+    private readonly heartbeat;
+    private readonly reconnector;
+    private token;
+    /** 连续鉴权失败次数。握手一成功就清零——只有**连续**失败才说明票是死的。 */
+    private authFailures;
+    private readonly tokenExpiry;
+    /** 「服务端已经彻底放弃这条会话」的倒计时。见 `ResumeDeadline`。 */
+    private readonly resumeDeadline;
+    constructor(options: ConnectionOptions);
+    /** currentState 返回连接状态。 */
+    get currentState(): ConnectionState;
+    /** currentSessionId 返回会话 id；重连时会带上它请求恢复。 */
+    get currentSessionId(): string;
+    /**
+     * updateToken 换一枚新的接入票（旧票过期时用）。下次连接生效。
+     *
+     * **顺带把鉴权失败计数清零**：换票就是「这次不一样了」的唯一信号，
+     * 不清的话已经用光重试次数的连接换了新票也再没有机会试。
+     */
+    updateToken(token: string, expiresAtMs?: number): void;
+    /** connect 建立连接并完成握手。已连上时直接返回。 */
+    connect(): Promise<HelloOk>;
+    /** close 主动关闭，**不会**触发重连。 */
+    close(): void;
+    /**
+     * request 发一个请求并等它的应答。
+     *
+     * 返回的 data 是**已按帧声明解码**的对象；未注册的应答类型返回原始 data。
+     */
+    request(type: string, fields: FrameFields, value: Record<string, unknown>): Promise<{
+        envelope: Envelope;
+        data: Record<string, unknown>;
+    }>;
+    /**
+     * dispatchRequest 不检查连接状态。
+     *
+     * 独立出来是因为 **sys.hello 本身就要在 connecting 状态下发出去**——
+     * 让握手走公开的 request() 会被状态检查挡住（踩过一次：所有时序测试都挂在
+     * 「一帧都没发出去」）。
+     */
+    private dispatchRequest;
+    /** send 发一帧但不等应答（服务端主动事件的回应，如 sub 的 answer）。 */
+    sendFrame(type: string, reqId: string, fields: FrameFields, value: Record<string, unknown>): void;
+    /**
+     * fire 发一个请求但**不等应答**：应答照常按 req_id 配对后丢掉，不会漏进事件流。
+     *
+     * 只给 `CallEngine.forceEnd()` 用：结束帧不许排在帧循环与在途请求后面
+     * （2026-09-13 iOS 那次挂断一帧没发出去，卡的正是那一段）。
+     * 帧在这次调用里就同步写进 socket（`dispatchRequest` 在第一个 await 之前就 send 了）。
+     * 未连接时只记一条日志——握手之前发业务帧会被服务端当成协议错误。
+     */
+    fire(type: string, fields: FrameFields, value: Record<string, unknown>): void;
+    private nextReqId;
+    private handshake;
+    /**
+     * 握手被拒且重试不可能变好时，一次就放弃，按 {@link handshakeGiveUpReason} 的分类抛给宿主。
+     *
+     * **握手应答类型不对那条不走这里**——那是对端的实现 bug，处置另说，
+     * 不该借这条路悄悄改掉。
+     */
+    private abortIfHandshakeRejected;
+    private handleMessage;
+    private dispatchEvent;
+    /**
+     * decodeData 返回**线路形状**（snake_case）的规范化 data。
+     *
+     * 「解出来再编回去」看着多余，其实是在做三件事：填默认值、枚举兜底、数值钳制。
+     * 保持 snake_case 是因为**状态机吃的是线路形状**——它跑的一致性向量就是线路形状，
+     * 换成 camelCase 会让状态机与向量之间多一层翻译，而那层翻译没人测。
+     *
+     * # 解不动就按原始 data 放行，**绝不往上抛**
+     *
+     * 这里原先是裸的 `decodeFields`。字段类型对不上（服务端把 int 位置发成了字符串）时它抛
+     * `bad_params`，而调用点在 `PendingRequests.settle` 里——那时 waiter **已经被摘掉、
+     * 超时也已经清掉**，`resolve` 却还没执行：那个 `request()` 的 promise 从此永远不落定。
+     * 症状是 `room.join.ok` 明明回来了，房间机却永远停在 `joining`，之后每次 publish 被
+     * R1 拒成 2005，而宿主一条错误都收不到（异常从 `onmessage` 里冲出去成了未捕获错误）。
+     * iOS（`(try? decodedData()) ?? envelope.data`）与 Android（catch 后回退 `envelope.data`）
+     * 本来就是这么做的，本端是四端里唯一漏掉兜底的。
+     *
+     * 回退之后字段读取一律走 `Wire.*` 那套「读不出来就取零值」的取数器，状态机不会崩；
+     * 真正的原因进日志 + 一条 error 事件，不塞进应答里让业务分不清。
+     */
+    private decodeData;
+    private handleClose;
+    /** sendPing 发一个心跳帧。连接不可用时静默跳过——心跳失败自有判死逻辑接手。 */
+    private sendPing;
+    private emitError;
+}
+//# sourceMappingURL=connection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/signaling/connection.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAWxF;;;;;;;GAOG;AAEH,YAAY,EACV,eAAe,EACf,OAAO,EACP,eAAe,EACf,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAgB9B,8CAA8C;AAC9C,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CACoB;IAE5C,OAAO,CAAC,EAAE,CAA8B;IACxC,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAE1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,KAAK,CAAS;IACtB,4CAA4C;IAC5C,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;IAC/C,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;gBAEpC,OAAO,EAAE,iBAAiB;IAkCtC,2BAA2B;IAC3B,IAAI,YAAY,IAAI,eAAe,CAElC;IAED,4CAA4C;IAC5C,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAQtD,kCAAkC;IAC5B,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IA4BjC,6BAA6B;IAC7B,KAAK,IAAI,IAAI;IAYb;;;;OAIG;IACG,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAUjE;;;;;;OAMG;YACW,eAAe;IAyB7B,gDAAgD;IAChD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAMjG;;;;;;;OAOG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAa7E,OAAO,CAAC,SAAS;YAKH,SAAS;IAqCvB;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB;IAYhC,OAAO,CAAC,aAAa;IAmBrB,OAAO,CAAC,aAAa;IAerB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,WAAW;IAwCnB,gDAAgD;IAChD,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,SAAS;CAKlB"}