im-rtc-call-engine 1.0.0

package/dist/engineWiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engineWiring.d.ts","sourceRoot":"","sources":["../src/engineWiring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AACjF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE9D;;;;;;;GAOG;AAEH,iCAAiC;AACjC,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB;;OAEG;IACH,UAAU,EAAE,MAAM,UAAU,GAAG,IAAI,CAAC;CACrC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,YAAY,GAAG,cAAc,CAS/D;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,CAAC,EAAE,YAAY,EACf,gBAAgB,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,GACjD,wBAAwB,CAiC1B"}

package/dist/engineWiring.js

@@ -0,0 +1,57 @@
+import { renegotiateAfterResume } from './media/mediaPlane.js';
+/**
+ * engineMediaDeps 是交给媒体接线的那一小把依赖（见 media/mediaPlane.ts）。
+ *
+ * `uidOf` 同样读的是状态机的**当前**快照，理由和 `connection` 那条一样。
+ */
+export function engineMediaDeps(w) {
+    return {
+        bridge: w.bridge,
+        bus: w.bus,
+        sender: w.sender,
+        connection: w.connection,
+        uidOf: (trackId) => w.loop.state.room.remoteTracks[trackId]?.uid ?? '',
+        dispatch: (input) => w.loop.dispatch(input),
+    };
+}
+/**
+ * engineConnectionHandlers 把连接层的回调接到状态机与事件总线上。
+ *
+ * `noteHelloApplied` 是回给门面的那条线：`login()` 要 await「hello.ok 已经喂进状态机」，
+ * 而握手结果**每一次**都从这里进来（包括自动重连那些），所以 promise 只能由这里产出。
+ */
+export function engineConnectionHandlers(w, noteHelloApplied) {
+    return {
+        // **握手结果一律从这里进状态机**，`login()` 不再自己喂一遍。
+        // 为什么（连同那次实测症状）写在 `EngineConnectionHandlers.onConnected` 上。
+        onConnected: (hello) => {
+            const applied = w.loop
+                .dispatch({
+                kind: 'recv',
+                type: 'sys.hello.ok',
+                data: { session_id: hello.sessionId, resumed: hello.resumed },
+            })
+                .then(async () => {
+                // 恢复之后要重新协商上行（§1.4）。**为什么触发点在这里**见 renegotiateAfterResume。
+                if (hello.resumed)
+                    await renegotiateAfterResume(engineMediaDeps(w));
+            });
+            noteHelloApplied(applied);
+            void applied.catch((err) => w.bus.emitError(err));
+        },
+        onEvent: (type, data) => void w.loop.handleIncoming(type, data),
+        onDisconnected: (info) => {
+            void w.loop.dispatch({ kind: 'internal', name: 'disconnected' });
+            w.bus.emit('disconnected', info);
+        },
+        onSessionUnrecoverable: () => void w.loop.dispatch({ kind: 'internal', name: 'session_unrecoverable' }),
+        onKickedOut: (info) => {
+            // 状态机只认「被踢了」这一件事，原因是给宿主做处置判断的，两者分开走。
+            void w.loop.dispatch({ kind: 'internal', name: 'ws_closed_4403' });
+            w.bus.emit('kickedOut', info);
+        },
+        onTokenWillExpire: (info) => w.bus.emit('tokenWillExpire', info),
+        onError: (error) => w.bus.emitError(error),
+    };
+}
+//# sourceMappingURL=engineWiring.js.map

package/dist/engineWiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engineWiring.js","sourceRoot":"","sources":["../src/engineWiring.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AA0B/D;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,CAAe;IAC7C,OAAO;QACL,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,KAAK,EAAE,CAAC,OAAO,EAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,GAAG,IAAI,EAAE;QAC9E,QAAQ,EAAE,CAAC,KAAK,EAAiB,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;KAC3D,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CACtC,CAAe,EACf,gBAAkD;IAElD,OAAO;QACL,uCAAuC;QACvC,4DAA4D;QAC5D,WAAW,EAAE,CAAC,KAAK,EAAQ,EAAE;YAC3B,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI;iBACnB,QAAQ,CAAC;gBACR,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,cAAc;gBACpB,IAAI,EAAE,EAAE,UAAU,EAAE,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE;aAC9D,CAAC;iBACD,IAAI,CAAC,KAAK,IAAI,EAAE;gBACf,2DAA2D;gBAC3D,IAAI,KAAK,CAAC,OAAO;oBAAE,MAAM,sBAAsB,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;YACtE,CAAC,CAAC,CAAC;YACL,gBAAgB,CAAC,OAAO,CAAC,CAAC;YAC1B,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7D,CAAC;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC;QACrE,cAAc,EAAE,CAAC,IAAI,EAAQ,EAAE;YAC7B,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC;YACjE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;QACnC,CAAC;QACD,sBAAsB,EAAE,GAAS,EAAE,CACjC,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,uBAAuB,EAAE,CAAC;QAC3E,WAAW,EAAE,CAAC,IAAI,EAAQ,EAAE;YAC1B,qCAAqC;YACrC,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC,CAAC;YACnE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QAChC,CAAC;QACD,iBAAiB,EAAE,CAAC,IAAI,EAAQ,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,iBAAiB,EAAE,IAAI,CAAC;QACtE,OAAO,EAAE,CAAC,KAAK,EAAQ,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC;KACjD,CAAC;AACJ,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,185 @@
+/**
+ * 错误码：**四仓共用同一份定义**，单一真相源是
+ * `im-rtc-server/docs/conformance/error_codes.json`（由 RTC_PROTOCOL.md §7 定稿）。
+ *
+ * 本文件的表由那份 JSON 手工同步而来，`test/conformance.test.ts` 逐条断言两者相等——
+ * 加了码却忘了同步，测试立刻挂。
+ *
+ * 两条硬约束：
+ * - `msg` 是**英文固定短语**，四端必须完全一致；它给开发者看，
+ *   **禁止直接显示给用户**，UI 文案由各端按 code 查自己的本地化表。
+ * - 2xxx 段是**客户端本地错误码**，永远不会出现在线路上。
+ */
+/** ErrorCode 是稳定的错误码。**只增不改不删**。 */
+export declare const ErrorCode: {
+    /** 信封字段缺失/类型错/data 为 null */
+    readonly badEnvelope: 1001;
+    /** 未知 type */
+    readonly unknownType: 1002;
+    /** 会议层留位帧，v1 未实现 */
+    readonly notImplemented: 1003;
+    /** data 字段非法：超长、枚举越界、数组含自己 */
+    readonly badParams: 1004;
+    /** 单帧超过 64 KiB */
+    readonly frameTooLarge: 1005;
+    /** sys.hello.protocol_version 不受支持 */
+    readonly protocolVersionUnsupported: 1006;
+    /** 上行频率超限 */
+    readonly rateLimited: 1007;
+    /** token 签名/受众/绑定关系错 */
+    readonly tokenInvalid: 1101;
+    /** token 过期，换新的重试 */
+    readonly tokenExpired: 1102;
+    /** 未发 sys.hello 就发别的帧 */
+    readonly notAuthenticated: 1103;
+    /** 同 uid 同 device_id 在别处登录 */
+    readonly kickedOut: 1104;
+    /** session_id 无效或超出 30s 恢复窗口 */
+    readonly sessionNotResumable: 1105;
+    /** 票据合法，但该 app_id 已被控制台停用 */
+    readonly appDisabled: 1106;
+    /** 房间不存在或已关闭 */
+    readonly roomNotFound: 1201;
+    /** 超出 max_participants */
+    readonly roomFull: 1202;
+    /** 未 join 就发房间帧 */
+    readonly notInRoom: 1203;
+    /** 重复 join 同一房间 */
+    readonly alreadyInRoom: 1204;
+    /** 房间已被解散 */
+    readonly roomClosed: 1205;
+    /** 无该操作权限 */
+    readonly permissionDenied: 1206;
+    /** 目标 participant 不在房 */
+    readonly participantNotFound: 1207;
+    /** 订阅/退订不存在的 track */
+    readonly trackNotFound: 1301;
+    /** 同 source 重复发布或房间策略禁止 */
+    readonly publishDenied: 1302;
+    /** 订阅自己的 track 或无订阅权限 */
+    readonly subscribeDenied: 1303;
+    /** SDP 解析失败/超长/cid 认不回来/在非 offerer 侧发 offer */
+    readonly sdpInvalid: 1304;
+    /** pc 对应的 PeerConnection 不存在 */
+    readonly pcNotFound: 1305;
+    /** max_layer 取值非法 */
+    readonly layerUnavailable: 1306;
+    /** SDP 里没有共同编码 */
+    readonly codecUnsupported: 1307;
+    /** call_id 不存在 */
+    readonly callNotFound: 1401;
+    /** 通话已结束，客户端必须静默吞掉 */
+    readonly callEnded: 1402;
+    /** 保留：v1 走 call.ended{offline} 而非报错 */
+    readonly calleeOffline: 1403;
+    /** 保留：v1 走 call.ended{busy} 而非报错 */
+    readonly calleeBusy: 1404;
+    /** 在错误状态下 accept/reject/cancel/hangup */
+    readonly invalidCallState: 1405;
+    /** callee_ids 超上限 */
+    readonly tooManyCallees: 1406;
+    /** 非主叫发 call.cancel；不在通话里的人发 call.invite_more */
+    readonly notCallOwner: 1407;
+    /** 自己已在别的通话中 */
+    readonly alreadyInCall: 1408;
+    /** 宿主的邀请鉴权回调拒绝了 call.invite / call.invite_more / call.join（或回调失败且应用配成拒绝） */
+    readonly inviteDenied: 1409;
+    /** 内部错误兜底 */
+    readonly internal: 1501;
+    /** 无可用 SFU 节点 */
+    readonly sfuUnavailable: 1502;
+    /** 服务端正在优雅关闭 */
+    readonly shuttingDown: 1503;
+    /** 持久化失败 */
+    readonly storeError: 1504;
+    /** 用户拒绝麦克风/摄像头权限 */
+    readonly devicePermissionDenied: 2001;
+    /** 没有可用的采集设备 */
+    readonly deviceNotFound: 2002;
+    /** 信令连不上、DNS/TLS 失败 */
+    readonly networkUnreachable: 2003;
+    /** 请求 10 秒无应答 */
+    readonly signalingTimeout: 2004;
+    /** 宿主在错误状态下调 Engine 方法 */
+    readonly invalidState: 2005;
+    /** PeerConnection 协商失败 / ICE failed */
+    readonly mediaNegotiationFailed: 2006;
+    /** 未 login 就调业务方法 */
+    readonly notLoggedIn: 2007;
+};
+/** ErrorCodeName 是错误码的键名联合。 */
+export type ErrorCodeName = keyof typeof ErrorCode;
+/** ErrorCodeValue 是错误码的数值联合。 */
+export type ErrorCodeValue = (typeof ErrorCode)[ErrorCodeName];
+/** ErrorDefinition 是一个错误码的全部契约面。 */
+export interface ErrorDefinition {
+    readonly code: number;
+    /** 稳定机读名，与 code 一一对应。 */
+    readonly name: string;
+    /** 英文固定短语，四端必须完全一致。 */
+    readonly msg: string;
+    /** true = 原样重试可能成功。 */
+    readonly retryable: boolean;
+    /** true = 客户端本地错误码（2xxx），永不上线路。 */
+    readonly local: boolean;
+}
+/** ERROR_DEFINITIONS 的顺序与 error_codes.json 一致，便于对读。 */
+export declare const ERROR_DEFINITIONS: readonly ErrorDefinition[];
+/** lookupError 按 code 查定义；未知码返回 undefined。 */
+export declare function lookupError(code: number): ErrorDefinition | undefined;
+/** errorName 返回错误码的机读名；未知码返回 'unknown'。 */
+export declare function errorName(code: number): string;
+/** isRetryable 报告这个码是否值得原样重试；未知码保守地按不可重试处理。 */
+export declare function isRetryable(code: number): boolean;
+/** isLocalError 报告这个码是不是客户端本地码（永不上线路）。 */
+export declare function isLocalError(code: number): boolean;
+/**
+ * RtcError 是 engine 对外抛的统一错误。
+ *
+ * `cause` 只用于日志，**不参与任何面向用户的展示**——这是「不把内部错误
+ * 透传给用户」那条规矩在 TS 侧的落点。
+ */
+export declare class RtcError extends Error {
+    readonly code: number;
+    readonly name_: string;
+    readonly retryable: boolean;
+    /** 出错的请求 type；无对应请求时为 ''。 */
+    readonly forType: string;
+    /**
+     * 本端不认识线路上那个码时，帧上自带的 `retryable`；认识就是 `undefined`。
+     *
+     * 为什么要单独留这一手：未知码在下面会被折成 `internal`（1501，而它
+     * `retryable === true`），于是**服务端新加的终局码在本端一律长成「可重试」**，
+     * 握手被拒也会退回无限重连。本端这张表只是上次同步时的快照，服务端比我们新是常态——
+     * 所以未知码一概以帧上带的那一位为准，不信折算后的码。
+     * Android 侧漏过 1106 一次，症状正是这个形状。
+     */
+    readonly unknownCodeRetryable: boolean | undefined;
+    constructor(code: number, options?: {
+        forType?: string;
+        cause?: unknown;
+        wireRetryable?: boolean;
+    });
+    /** wireShape 返回可以放进 sys.error 的 data —— 注意**不含** cause。 */
+    wireShape(): {
+        code: number;
+        name: string;
+        msg: string;
+        for_type: string;
+        retryable: boolean;
+    };
+}
+/**
+ * rtcErrorFromWire 把一帧 `sys.error` 的 data 翻成 `RtcError`。
+ *
+ * **同一条不变量只该有一份实现。** 过去两个调用点（在途请求的结算、无主的错误帧）
+ * 各写了一遍这段构造，于是「未知码要留住帧上的 `retryable`」这条只在其中一处成立——
+ * 而握手恰恰走的是另一处，未知的终局码照样退回无限重连。
+ *
+ * `fallbackForType` 是 `for_type` 缺失时的兜底：结算在途请求时用那个请求自己的 type，
+ * 无主错误帧则没什么可兜的。
+ */
+export declare function rtcErrorFromWire(data: Record<string, unknown>, fallbackForType?: string): RtcError;
+/** isRtcError 是 RtcError 的类型守卫。 */
+export declare function isRtcError(err: unknown): err is RtcError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

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

package/dist/errors.js

@@ -0,0 +1,253 @@
+/**
+ * 错误码：**四仓共用同一份定义**，单一真相源是
+ * `im-rtc-server/docs/conformance/error_codes.json`（由 RTC_PROTOCOL.md §7 定稿）。
+ *
+ * 本文件的表由那份 JSON 手工同步而来，`test/conformance.test.ts` 逐条断言两者相等——
+ * 加了码却忘了同步，测试立刻挂。
+ *
+ * 两条硬约束：
+ * - `msg` 是**英文固定短语**，四端必须完全一致；它给开发者看，
+ *   **禁止直接显示给用户**，UI 文案由各端按 code 查自己的本地化表。
+ * - 2xxx 段是**客户端本地错误码**，永远不会出现在线路上。
+ */
+/** ErrorCode 是稳定的错误码。**只增不改不删**。 */
+export const ErrorCode = {
+    /** 信封字段缺失/类型错/data 为 null */
+    badEnvelope: 1001,
+    /** 未知 type */
+    unknownType: 1002,
+    /** 会议层留位帧，v1 未实现 */
+    notImplemented: 1003,
+    /** data 字段非法：超长、枚举越界、数组含自己 */
+    badParams: 1004,
+    /** 单帧超过 64 KiB */
+    frameTooLarge: 1005,
+    /** sys.hello.protocol_version 不受支持 */
+    protocolVersionUnsupported: 1006,
+    /** 上行频率超限 */
+    rateLimited: 1007,
+    /** token 签名/受众/绑定关系错 */
+    tokenInvalid: 1101,
+    /** token 过期，换新的重试 */
+    tokenExpired: 1102,
+    /** 未发 sys.hello 就发别的帧 */
+    notAuthenticated: 1103,
+    /** 同 uid 同 device_id 在别处登录 */
+    kickedOut: 1104,
+    /** session_id 无效或超出 30s 恢复窗口 */
+    sessionNotResumable: 1105,
+    /** 票据合法，但该 app_id 已被控制台停用 */
+    appDisabled: 1106,
+    /** 房间不存在或已关闭 */
+    roomNotFound: 1201,
+    /** 超出 max_participants */
+    roomFull: 1202,
+    /** 未 join 就发房间帧 */
+    notInRoom: 1203,
+    /** 重复 join 同一房间 */
+    alreadyInRoom: 1204,
+    /** 房间已被解散 */
+    roomClosed: 1205,
+    /** 无该操作权限 */
+    permissionDenied: 1206,
+    /** 目标 participant 不在房 */
+    participantNotFound: 1207,
+    /** 订阅/退订不存在的 track */
+    trackNotFound: 1301,
+    /** 同 source 重复发布或房间策略禁止 */
+    publishDenied: 1302,
+    /** 订阅自己的 track 或无订阅权限 */
+    subscribeDenied: 1303,
+    /** SDP 解析失败/超长/cid 认不回来/在非 offerer 侧发 offer */
+    sdpInvalid: 1304,
+    /** pc 对应的 PeerConnection 不存在 */
+    pcNotFound: 1305,
+    /** max_layer 取值非法 */
+    layerUnavailable: 1306,
+    /** SDP 里没有共同编码 */
+    codecUnsupported: 1307,
+    /** call_id 不存在 */
+    callNotFound: 1401,
+    /** 通话已结束，客户端必须静默吞掉 */
+    callEnded: 1402,
+    /** 保留：v1 走 call.ended{offline} 而非报错 */
+    calleeOffline: 1403,
+    /** 保留：v1 走 call.ended{busy} 而非报错 */
+    calleeBusy: 1404,
+    /** 在错误状态下 accept/reject/cancel/hangup */
+    invalidCallState: 1405,
+    /** callee_ids 超上限 */
+    tooManyCallees: 1406,
+    /** 非主叫发 call.cancel；不在通话里的人发 call.invite_more */
+    notCallOwner: 1407,
+    /** 自己已在别的通话中 */
+    alreadyInCall: 1408,
+    /** 宿主的邀请鉴权回调拒绝了 call.invite / call.invite_more / call.join（或回调失败且应用配成拒绝） */
+    inviteDenied: 1409,
+    /** 内部错误兜底 */
+    internal: 1501,
+    /** 无可用 SFU 节点 */
+    sfuUnavailable: 1502,
+    /** 服务端正在优雅关闭 */
+    shuttingDown: 1503,
+    /** 持久化失败 */
+    storeError: 1504,
+    /** 用户拒绝麦克风/摄像头权限 */
+    devicePermissionDenied: 2001,
+    /** 没有可用的采集设备 */
+    deviceNotFound: 2002,
+    /** 信令连不上、DNS/TLS 失败 */
+    networkUnreachable: 2003,
+    /** 请求 10 秒无应答 */
+    signalingTimeout: 2004,
+    /** 宿主在错误状态下调 Engine 方法 */
+    invalidState: 2005,
+    /** PeerConnection 协商失败 / ICE failed */
+    mediaNegotiationFailed: 2006,
+    /** 未 login 就调业务方法 */
+    notLoggedIn: 2007,
+};
+/** ERROR_DEFINITIONS 的顺序与 error_codes.json 一致，便于对读。 */
+export const ERROR_DEFINITIONS = [
+    { code: 1001, name: 'bad_envelope', msg: 'malformed envelope', retryable: false, local: false },
+    { code: 1002, name: 'unknown_type', msg: 'unknown frame type', retryable: false, local: false },
+    { code: 1003, name: 'not_implemented', msg: 'frame not implemented', retryable: false, local: false },
+    { code: 1004, name: 'bad_params', msg: 'invalid frame parameters', retryable: false, local: false },
+    { code: 1005, name: 'frame_too_large', msg: 'frame too large', retryable: false, local: false },
+    { code: 1006, name: 'protocol_version_unsupported', msg: 'protocol version unsupported', retryable: false, local: false },
+    { code: 1007, name: 'rate_limited', msg: 'rate limited', retryable: true, local: false },
+    { code: 1101, name: 'token_invalid', msg: 'token invalid', retryable: false, local: false },
+    { code: 1102, name: 'token_expired', msg: 'token expired', retryable: true, local: false },
+    { code: 1103, name: 'not_authenticated', msg: 'not authenticated', retryable: false, local: false },
+    { code: 1104, name: 'kicked_out', msg: 'kicked out', retryable: false, local: false },
+    { code: 1105, name: 'session_not_resumable', msg: 'session not resumable', retryable: false, local: false },
+    // 票据合法但该 app_id 已被停用（宿主在控制台停用了整个应用）。
+    // 与 1101/1102 不同：那两个是「换张票再来」，这个是「这个应用被停了」。
+    { code: 1106, name: 'app_disabled', msg: 'application disabled', retryable: false, local: false },
+    { code: 1201, name: 'room_not_found', msg: 'room not found', retryable: false, local: false },
+    { code: 1202, name: 'room_full', msg: 'room is full', retryable: false, local: false },
+    { code: 1203, name: 'not_in_room', msg: 'not in room', retryable: false, local: false },
+    { code: 1204, name: 'already_in_room', msg: 'already in room', retryable: false, local: false },
+    { code: 1205, name: 'room_closed', msg: 'room closed', retryable: false, local: false },
+    { code: 1206, name: 'permission_denied', msg: 'permission denied', retryable: false, local: false },
+    { code: 1207, name: 'participant_not_found', msg: 'participant not found', retryable: false, local: false },
+    { code: 1301, name: 'track_not_found', msg: 'track not found', retryable: false, local: false },
+    { code: 1302, name: 'publish_denied', msg: 'publish denied', retryable: false, local: false },
+    { code: 1303, name: 'subscribe_denied', msg: 'subscribe denied', retryable: false, local: false },
+    { code: 1304, name: 'sdp_invalid', msg: 'sdp invalid', retryable: false, local: false },
+    { code: 1305, name: 'pc_not_found', msg: 'peer connection not found', retryable: false, local: false },
+    { code: 1306, name: 'layer_unavailable', msg: 'layer unavailable', retryable: false, local: false },
+    { code: 1307, name: 'codec_unsupported', msg: 'codec unsupported', retryable: false, local: false },
+    { code: 1401, name: 'call_not_found', msg: 'call not found', retryable: false, local: false },
+    { code: 1402, name: 'call_ended', msg: 'call already ended', retryable: false, local: false },
+    { code: 1403, name: 'callee_offline', msg: 'callee offline', retryable: false, local: false },
+    { code: 1404, name: 'callee_busy', msg: 'callee busy', retryable: false, local: false },
+    { code: 1405, name: 'invalid_call_state', msg: 'invalid call state', retryable: false, local: false },
+    { code: 1406, name: 'too_many_callees', msg: 'too many callees', retryable: false, local: false },
+    { code: 1407, name: 'not_call_owner', msg: 'not call owner', retryable: false, local: false },
+    { code: 1408, name: 'already_in_call', msg: 'already in call', retryable: false, local: false },
+    { code: 1409, name: 'invite_denied', msg: 'invite denied by host', retryable: false, local: false },
+    { code: 1501, name: 'internal', msg: 'internal error', retryable: true, local: false },
+    { code: 1502, name: 'sfu_unavailable', msg: 'sfu unavailable', retryable: true, local: false },
+    { code: 1503, name: 'shutting_down', msg: 'server shutting down', retryable: true, local: false },
+    { code: 1504, name: 'store_error', msg: 'store error', retryable: true, local: false },
+    { code: 2001, name: 'device_permission_denied', msg: 'device permission denied', retryable: false, local: true },
+    { code: 2002, name: 'device_not_found', msg: 'device not found', retryable: false, local: true },
+    { code: 2003, name: 'network_unreachable', msg: 'network unreachable', retryable: true, local: true },
+    { code: 2004, name: 'signaling_timeout', msg: 'signaling timeout', retryable: true, local: true },
+    { code: 2005, name: 'invalid_state', msg: 'invalid state', retryable: false, local: true },
+    { code: 2006, name: 'media_negotiation_failed', msg: 'media negotiation failed', retryable: false, local: true },
+    { code: 2007, name: 'not_logged_in', msg: 'not logged in', retryable: false, local: true },
+];
+const byCode = new Map(ERROR_DEFINITIONS.map((d) => [d.code, d]));
+/** lookupError 按 code 查定义；未知码返回 undefined。 */
+export function lookupError(code) {
+    return byCode.get(code);
+}
+/** errorName 返回错误码的机读名；未知码返回 'unknown'。 */
+export function errorName(code) {
+    return byCode.get(code)?.name ?? 'unknown';
+}
+/** isRetryable 报告这个码是否值得原样重试；未知码保守地按不可重试处理。 */
+export function isRetryable(code) {
+    return byCode.get(code)?.retryable ?? false;
+}
+/** isLocalError 报告这个码是不是客户端本地码（永不上线路）。 */
+export function isLocalError(code) {
+    return byCode.get(code)?.local ?? false;
+}
+/**
+ * RtcError 是 engine 对外抛的统一错误。
+ *
+ * `cause` 只用于日志，**不参与任何面向用户的展示**——这是「不把内部错误
+ * 透传给用户」那条规矩在 TS 侧的落点。
+ */
+export class RtcError extends Error {
+    code;
+    name_;
+    retryable;
+    /** 出错的请求 type；无对应请求时为 ''。 */
+    forType;
+    /**
+     * 本端不认识线路上那个码时，帧上自带的 `retryable`；认识就是 `undefined`。
+     *
+     * 为什么要单独留这一手：未知码在下面会被折成 `internal`（1501，而它
+     * `retryable === true`），于是**服务端新加的终局码在本端一律长成「可重试」**，
+     * 握手被拒也会退回无限重连。本端这张表只是上次同步时的快照，服务端比我们新是常态——
+     * 所以未知码一概以帧上带的那一位为准，不信折算后的码。
+     * Android 侧漏过 1106 一次，症状正是这个形状。
+     */
+    unknownCodeRetryable;
+    constructor(code, options = {}) {
+        const def = byCode.get(code);
+        // 兜底的 internal 一定存在：它是表里的固定项。
+        const resolved = (def ?? byCode.get(ErrorCode.internal));
+        super(`${resolved.name}(${resolved.code}): ${resolved.msg}`, { cause: options.cause });
+        this.name = 'RtcError';
+        this.code = resolved.code;
+        this.name_ = resolved.name;
+        this.retryable = resolved.retryable;
+        this.forType = options.forType ?? '';
+        // 「只有本端不认识才留」这条规矩收在这一处：认识的码不许被线路上的一位盖掉
+        // 一致性向量里的定义。
+        this.unknownCodeRetryable = def === undefined ? options.wireRetryable : undefined;
+    }
+    /** wireShape 返回可以放进 sys.error 的 data —— 注意**不含** cause。 */
+    wireShape() {
+        const def = byCode.get(this.code) ?? byCode.get(ErrorCode.internal);
+        const resolved = def;
+        return {
+            code: resolved.code,
+            name: resolved.name,
+            msg: resolved.msg,
+            for_type: this.forType,
+            retryable: resolved.retryable,
+        };
+    }
+}
+/**
+ * rtcErrorFromWire 把一帧 `sys.error` 的 data 翻成 `RtcError`。
+ *
+ * **同一条不变量只该有一份实现。** 过去两个调用点（在途请求的结算、无主的错误帧）
+ * 各写了一遍这段构造，于是「未知码要留住帧上的 `retryable`」这条只在其中一处成立——
+ * 而握手恰恰走的是另一处，未知的终局码照样退回无限重连。
+ *
+ * `fallbackForType` 是 `for_type` 缺失时的兜底：结算在途请求时用那个请求自己的 type，
+ * 无主错误帧则没什么可兜的。
+ */
+export function rtcErrorFromWire(data, fallbackForType = '') {
+    const code = data['code'];
+    const forType = data['for_type'];
+    const retryable = data['retryable'];
+    return new RtcError(typeof code === 'number' ? code : ErrorCode.internal, {
+        forType: typeof forType === 'string' ? forType : fallbackForType,
+        // 帧上没带就整个不传这个键：本仓开着 exactOptionalPropertyTypes，
+        // 显式传 undefined 与「没有这个键」不是一回事。
+        ...(typeof retryable === 'boolean' ? { wireRetryable: retryable } : {}),
+    });
+}
+/** isRtcError 是 RtcError 的类型守卫。 */
+export function isRtcError(err) {
+    return err instanceof RtcError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/eventBus.d.ts

@@ -0,0 +1,24 @@
+import type { EngineEventHandler, EngineEventName, EngineEvents } from './events.js';
+/**
+ * 类型安全的事件总线。
+ *
+ * 不引第三方 emitter：SDK 要轻，宿主的技术栈不该被我们绑架（CONVENTIONS §11）。
+ * 逻辑就这几十行。
+ */
+export declare class EventBus {
+    private readonly handlers;
+    /** on 订阅一个事件，返回退订函数。 */
+    on<K extends EngineEventName>(name: K, handler: EngineEventHandler<K>): () => void;
+    /** off 退订。 */
+    off<K extends EngineEventName>(name: K, handler: EngineEventHandler<K>): void;
+    /**
+     * emit 派发一个事件。
+     *
+     * **单个订阅者抛异常不能影响其他订阅者**——宿主的某个 UI 组件写崩了，
+     * 不该让整个通话的事件流断掉。
+     */
+    emit<K extends EngineEventName>(name: K, payload: EngineEvents[K]): void;
+    /** clear 清空全部订阅（engine 销毁时）。 */
+    clear(): void;
+}
+//# sourceMappingURL=eventBus.d.ts.map

package/dist/eventBus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventBus.d.ts","sourceRoot":"","sources":["../src/eventBus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGrF;;;;;GAKG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6D;IAEtF,wBAAwB;IACxB,EAAE,CAAC,CAAC,SAAS,eAAe,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAYlF,cAAc;IACd,GAAG,CAAC,CAAC,SAAS,eAAe,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,IAAI;IAI7E;;;;;OAKG;IACH,IAAI,CAAC,CAAC,SAAS,eAAe,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IAYxE,gCAAgC;IAChC,KAAK,IAAI,IAAI;CAGd"}

package/dist/eventBus.js

@@ -0,0 +1,50 @@
+import { logger } from './logger.js';
+/**
+ * 类型安全的事件总线。
+ *
+ * 不引第三方 emitter：SDK 要轻，宿主的技术栈不该被我们绑架（CONVENTIONS §11）。
+ * 逻辑就这几十行。
+ */
+export class EventBus {
+    handlers = new Map();
+    /** on 订阅一个事件，返回退订函数。 */
+    on(name, handler) {
+        let set = this.handlers.get(name);
+        if (set === undefined) {
+            set = new Set();
+            this.handlers.set(name, set);
+        }
+        set.add(handler);
+        return () => {
+            set?.delete(handler);
+        };
+    }
+    /** off 退订。 */
+    off(name, handler) {
+        this.handlers.get(name)?.delete(handler);
+    }
+    /**
+     * emit 派发一个事件。
+     *
+     * **单个订阅者抛异常不能影响其他订阅者**——宿主的某个 UI 组件写崩了，
+     * 不该让整个通话的事件流断掉。
+     */
+    emit(name, payload) {
+        const set = this.handlers.get(name);
+        if (set === undefined)
+            return;
+        for (const handler of [...set]) {
+            try {
+                handler(payload);
+            }
+            catch (cause) {
+                logger.error('事件订阅者抛异常', { event: name, cause: String(cause) });
+            }
+        }
+    }
+    /** clear 清空全部订阅（engine 销毁时）。 */
+    clear() {
+        this.handlers.clear();
+    }
+}
+//# sourceMappingURL=eventBus.js.map

package/dist/eventBus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventBus.js","sourceRoot":"","sources":["../src/eventBus.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;GAKG;AACH,MAAM,OAAO,QAAQ;IACF,QAAQ,GAAG,IAAI,GAAG,EAAkD,CAAC;IAEtF,wBAAwB;IACxB,EAAE,CAA4B,IAAO,EAAE,OAA8B;QACnE,IAAI,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC/B,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,OAAmC,CAAC,CAAC;QAC7C,OAAO,GAAG,EAAE;YACV,GAAG,EAAE,MAAM,CAAC,OAAmC,CAAC,CAAC;QACnD,CAAC,CAAC;IACJ,CAAC;IAED,cAAc;IACd,GAAG,CAA4B,IAAO,EAAE,OAA8B;QACpE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,OAAmC,CAAC,CAAC;IACvE,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAA4B,IAAO,EAAE,OAAwB;QAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO;QAC9B,KAAK,MAAM,OAAO,IAAI,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC;gBACF,OAAiC,CAAC,OAAO,CAAC,CAAC;YAC9C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAClE,CAAC;QACH,CAAC;IACH,CAAC;IAED,gCAAgC;IAChC,KAAK;QACH,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;CACF"}