im-rtc-call-engine 1.0.0 → 2.1.0

package/dist/browserSignals.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 浏览器替宿主盯两件事：标签页回到前台（`visibilitychange`）、网络变了（`online` 与
+ * `navigator.connection` 的 `change`），转成 `Connection.setAppForeground` / `notifyNetworkChanged`。
+ *
+ * iOS / Android 由 Kit 喂这两个信号；Web 没有「Kit 起来了」这个时机，而这些事件在浏览器里是全局的，
+ * 所以登录时由 `EngineSession` 自己挂上、登出摘掉——**宿主什么都不用写**。宿主自己再调
+ * `CallEngine.setAppForeground` / `notifyNetworkChanged` 也无妨：探测一次只探一个，立刻重连两次至少隔 2 秒。
+ *
+ * 不在浏览器里（Node 单测、SSR）就什么都不挂。
+ */
+/** BrowserSignalTarget 是收信号的那一方（`Connection`）。 */
+export interface BrowserSignalTarget {
+    setAppForeground(foreground: boolean): void;
+    notifyNetworkChanged(): void;
+}
+/** BrowserEnv 是要听的三个事件源，单测可注入。 */
+export interface BrowserEnv {
+    readonly document?: (EventTarget & {
+        readonly visibilityState: string;
+    }) | undefined;
+    readonly window?: EventTarget | undefined;
+    /** `navigator.connection`（Chrome 系有，Safari / Firefox 没有）。 */
+    readonly connection?: EventTarget | undefined;
+}
+/** watchBrowserSignals 挂上监听，返回摘除函数。 */
+export declare function watchBrowserSignals(target: BrowserSignalTarget, env?: BrowserEnv): () => void;
+//# sourceMappingURL=browserSignals.d.ts.map

package/dist/browserSignals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserSignals.d.ts","sourceRoot":"","sources":["../src/browserSignals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,kDAAkD;AAClD,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,CAAC,UAAU,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,oBAAoB,IAAI,IAAI,CAAC;CAC9B;AAED,kCAAkC;AAClC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,WAAW,GAAG;QAAE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,SAAS,CAAC;IACrF,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC/C;AAWD,uCAAuC;AACvC,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,EAAE,GAAG,GAAE,UAAyB,GAAG,MAAM,IAAI,CAe3G"}

package/dist/browserSignals.js

@@ -0,0 +1,34 @@
+/**
+ * 浏览器替宿主盯两件事：标签页回到前台（`visibilitychange`）、网络变了（`online` 与
+ * `navigator.connection` 的 `change`），转成 `Connection.setAppForeground` / `notifyNetworkChanged`。
+ *
+ * iOS / Android 由 Kit 喂这两个信号；Web 没有「Kit 起来了」这个时机，而这些事件在浏览器里是全局的，
+ * 所以登录时由 `EngineSession` 自己挂上、登出摘掉——**宿主什么都不用写**。宿主自己再调
+ * `CallEngine.setAppForeground` / `notifyNetworkChanged` 也无妨：探测一次只探一个，立刻重连两次至少隔 2 秒。
+ *
+ * 不在浏览器里（Node 单测、SSR）就什么都不挂。
+ */
+function defaultEnv() {
+    const g = globalThis;
+    return { document: g.document, window: g.window, connection: g.navigator?.connection };
+}
+/** watchBrowserSignals 挂上监听，返回摘除函数。 */
+export function watchBrowserSignals(target, env = defaultEnv()) {
+    const removers = [];
+    const listen = (source, type, handler) => {
+        if (source === undefined || typeof source.addEventListener !== 'function')
+            return;
+        source.addEventListener(type, handler);
+        removers.push(() => source.removeEventListener(type, handler));
+    };
+    const doc = env.document;
+    listen(doc, 'visibilitychange', () => target.setAppForeground(doc?.visibilityState === 'visible'));
+    // 断网期间不报：没网可连。`online` 就是「从没网恢复到有网」。
+    listen(env.window, 'online', () => target.notifyNetworkChanged());
+    listen(env.connection, 'change', () => target.notifyNetworkChanged());
+    return () => {
+        for (const remove of removers.splice(0))
+            remove();
+    };
+}
+//# sourceMappingURL=browserSignals.js.map

package/dist/browserSignals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserSignals.js","sourceRoot":"","sources":["../src/browserSignals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAgBH,SAAS,UAAU;IACjB,MAAM,CAAC,GAAG,UAIT,CAAC;IACF,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC;AACzF,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,mBAAmB,CAAC,MAA2B,EAAE,MAAkB,UAAU,EAAE;IAC7F,MAAM,QAAQ,GAAmB,EAAE,CAAC;IACpC,MAAM,MAAM,GAAG,CAAC,MAA+B,EAAE,IAAY,EAAE,OAAmB,EAAQ,EAAE;QAC1F,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,MAAM,CAAC,gBAAgB,KAAK,UAAU;YAAE,OAAO;QAClF,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACvC,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IACjE,CAAC,CAAC;IACF,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC;IACzB,MAAM,CAAC,GAAG,EAAE,kBAAkB,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC,GAAG,EAAE,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC;IACnG,qCAAqC;IACrC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,oBAAoB,EAAE,CAAC,CAAC;IAClE,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,oBAAoB,EAAE,CAAC,CAAC;IACtE,OAAO,GAAS,EAAE;QAChB,KAAK,MAAM,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;YAAE,MAAM,EAAE,CAAC;IACpD,CAAC,CAAC;AACJ,CAAC"}

package/dist/callGuards.d.ts

@@ -0,0 +1,35 @@
+import type { EngineBus } from './engineBus.js';
+import { RtcError } from './errors.js';
+/**
+ * rejectsSelf 挡住「名单里有自己」：返回要交给调用方的 `1004`，没问题时返回 null。
+ *
+ * 服务端会以 `1004 bad_params` 拒掉（"callee_ids 不能含主叫自己"），但那条链路上的
+ * 失败很难看懂：界面已经乐观地进了「正在呼叫…」，而错误只是一条没头没尾的 1004。
+ * （实测撞过：Demo 的群呼默认名单里正好有登录的那个人。）
+ *
+ * **一份实现供 call 与 inviteMore 共用**——两处各写一遍的话，改了一处忘了另一处，
+ * 就又是一个「同一条规则在一处成立、另一处不成立」。
+ */
+export declare function rejectsSelf(myUid: string, calleeIds: readonly string[], what: string, forType: string): RtcError | null;
+/**
+ * rejectsBadCallOptions 挡住超限的 `chatGroupId` / `userData`：返回要交给调用方的 `1004`，没问题时返回 null。
+ *
+ * 服务端会以 `1004 bad_params` 拒掉，但那条链路上主叫已经乐观地进了「正在呼叫…」，
+ * 错误只是一条没头没尾的 1004——与 {@link rejectsSelf} 同一个理由，本地先拦，
+ * 走同一个出口（HOST_INTEGRATION_DESIGN §3.3）。
+ */
+export declare function rejectsBadCallOptions(chatGroupId: string, userData: string): RtcError | null;
+/**
+ * emitLocallyRejectedCall 给「`call()` 被本地拒掉」一个出口：抛一条 `callEnd(error)`。
+ *
+ * 调用方（uikit / 宿主）在调 `call()` 之前就已经切到「正在呼叫…」了——
+ * 这是对的，不然按下去几百毫秒没反应。但只交回一个错误，
+ * 靠事件驱动的界面不知道该退回哪儿：实测三人测试里 carol 卡在「正在呼叫…」，
+ * 连点五次挂断收到五个 2005（状态机是 idle，没有 call 可挂），
+ * 除了刷新页面没有别的出路。
+ *
+ * `callEnd` 是所有结束分支的唯一出口（设计 §7.5），
+ * 这一条与「服务端拒了 invite」（call_failed）走同一个出口，界面只认它。
+ */
+export declare function emitLocallyRejectedCall(bus: EngineBus): void;
+//# sourceMappingURL=callGuards.d.ts.map

package/dist/callGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callGuards.d.ts","sourceRoot":"","sources":["../src/callGuards.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAa,QAAQ,EAAE,MAAM,aAAa,CAAC;AAclD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,QAAQ,GAAG,IAAI,CAIjB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAM5F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAO5D"}

package/dist/callGuards.js

@@ -0,0 +1,66 @@
+import { byteLength } from './bytes.js';
+import { violatesCallOptionLimits } from './callOptions.js';
+import { ErrorCode, RtcError } from './errors.js';
+import { logger } from './logger.js';
+import { CallEndReason } from './reasons.js';
+/*
+  发起类动作（`call` / `inviteMore`）上线路**之前**的本地关卡。
+
+  从 `engine.ts` 里单拎出来：门面只该留公开签名与给宿主看的文档，
+  「哪些参数本地先拦、拦了走哪个出口」是一段自成一体的规则，放在门面里只是让那个文件贴着体量红线。
+  判断本身是纯函数的那部分在 `callOptions.ts`；这里管的是日志与「拒了之后给界面的出口」。
+  拒绝本身**交给调用方**（门面 throw 返回的错误），不发 error 事件——一次失败只从一个出口报
+  （server `docs/design/ACTION_RESULT_DESIGN.md` R3）。
+*/
+/**
+ * rejectsSelf 挡住「名单里有自己」：返回要交给调用方的 `1004`，没问题时返回 null。
+ *
+ * 服务端会以 `1004 bad_params` 拒掉（"callee_ids 不能含主叫自己"），但那条链路上的
+ * 失败很难看懂：界面已经乐观地进了「正在呼叫…」，而错误只是一条没头没尾的 1004。
+ * （实测撞过：Demo 的群呼默认名单里正好有登录的那个人。）
+ *
+ * **一份实现供 call 与 inviteMore 共用**——两处各写一遍的话，改了一处忘了另一处，
+ * 就又是一个「同一条规则在一处成立、另一处不成立」。
+ */
+export function rejectsSelf(myUid, calleeIds, what, forType) {
+    if (myUid === '' || !calleeIds.includes(myUid))
+        return null;
+    logger.warn(`${what}名单里含自己，已就地拒掉`, { uid: myUid });
+    return new RtcError(ErrorCode.badParams, { forType });
+}
+/**
+ * rejectsBadCallOptions 挡住超限的 `chatGroupId` / `userData`：返回要交给调用方的 `1004`，没问题时返回 null。
+ *
+ * 服务端会以 `1004 bad_params` 拒掉，但那条链路上主叫已经乐观地进了「正在呼叫…」，
+ * 错误只是一条没头没尾的 1004——与 {@link rejectsSelf} 同一个理由，本地先拦，
+ * 走同一个出口（HOST_INTEGRATION_DESIGN §3.3）。
+ */
+export function rejectsBadCallOptions(chatGroupId, userData) {
+    if (!violatesCallOptionLimits(chatGroupId, userData))
+        return null;
+    logger.warn('chatGroupId / userData 超限，已就地拒掉', {
+        chatGroupId, userDataBytes: byteLength(userData),
+    });
+    return new RtcError(ErrorCode.badParams, { forType: 'call.invite' });
+}
+/**
+ * emitLocallyRejectedCall 给「`call()` 被本地拒掉」一个出口：抛一条 `callEnd(error)`。
+ *
+ * 调用方（uikit / 宿主）在调 `call()` 之前就已经切到「正在呼叫…」了——
+ * 这是对的，不然按下去几百毫秒没反应。但只交回一个错误，
+ * 靠事件驱动的界面不知道该退回哪儿：实测三人测试里 carol 卡在「正在呼叫…」，
+ * 连点五次挂断收到五个 2005（状态机是 idle，没有 call 可挂），
+ * 除了刷新页面没有别的出路。
+ *
+ * `callEnd` 是所有结束分支的唯一出口（设计 §7.5），
+ * 这一条与「服务端拒了 invite」（call_failed）走同一个出口，界面只认它。
+ */
+export function emitLocallyRejectedCall(bus) {
+    bus.emit('callEnd', {
+        callId: '',
+        reason: CallEndReason.error,
+        durationSec: 0,
+        endedBy: '',
+    });
+}
+//# sourceMappingURL=callGuards.js.map

package/dist/callGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callGuards.js","sourceRoot":"","sources":["../src/callGuards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C;;;;;;;;EAQE;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CACzB,KAAa,EACb,SAA4B,EAC5B,IAAY,EACZ,OAAe;IAEf,IAAI,KAAK,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5D,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,cAAc,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IACnD,OAAO,IAAI,QAAQ,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAAmB,EAAE,QAAgB;IACzE,IAAI,CAAC,wBAAwB,CAAC,WAAW,EAAE,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAClE,MAAM,CAAC,IAAI,CAAC,iCAAiC,EAAE;QAC7C,WAAW,EAAE,aAAa,EAAE,UAAU,CAAC,QAAQ,CAAC;KACjD,CAAC,CAAC;IACH,OAAO,IAAI,QAAQ,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC;AACvE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAc;IACpD,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE;QAClB,MAAM,EAAE,EAAE;QACV,MAAM,EAAE,aAAa,CAAC,KAAK;QAC3B,WAAW,EAAE,CAAC;QACd,OAAO,EAAE,EAAE;KACZ,CAAC,CAAC;AACL,CAAC"}

package/dist/callHistory.d.ts

@@ -0,0 +1,50 @@
+/** 通话记录里的一位成员。`state` 是这位成员在这通电话里的结局，原样透传。 */
+export interface CallHistoryMember {
+    readonly uid: string;
+    readonly state: string;
+}
+/**
+ * 一条通话记录，字段与服务端 `GET /v1/calls` 一一对应（camelCase）。
+ *
+ * `reason` 是通话的最终结局（`hangup` / `cancel` / `reject` / `no_answer`…），**不分角色**：
+ * 要显示「已取消」还是「对方已取消」，用 `caller` 与自己的 `uid` 比出角色再定文案。
+ */
+export interface CallHistoryRecord {
+    readonly callId: string;
+    readonly roomId: string;
+    readonly caller: string;
+    /** `audio` 或 `video`。 */
+    readonly mediaType: string;
+    readonly isGroup: boolean;
+    readonly reason: string;
+    readonly endedBy: string;
+    readonly durationSec: number;
+    readonly startedAtMs: number;
+    readonly connectedAtMs: number;
+    readonly endedAtMs: number;
+    readonly userData: string;
+    readonly chatGroupId: string;
+    readonly members: readonly CallHistoryMember[];
+}
+/** 一页通话记录（按发起时间倒序）。`nextCursor` 为 `null` 表示已经到底。 */
+export interface CallHistoryPage {
+    readonly records: readonly CallHistoryRecord[];
+    readonly nextCursor: number | null;
+}
+export interface FetchCallHistoryOptions {
+    /** 每页条数，夹在 1..200，默认 20。 */
+    readonly limit?: number;
+    /** 首页不传；下一页传上一页的 `nextCursor`。 */
+    readonly cursor?: number;
+}
+/** 服务端每页上限（`maxCallLimit`）。超过它服务端也只回这么多，「到底」的判据就不成立了，所以本地先夹住。 */
+export declare const MAX_CALL_HISTORY_LIMIT = 200;
+export declare const DEFAULT_CALL_HISTORY_LIMIT = 20;
+/** 信令地址推出 REST 根：`ws→http`、`wss→https`，去掉末尾的 `/v1/ws`。推不出返回 `null`。 */
+export declare function restBaseUrl(signalingUrl: string): string | null;
+export declare function callHistoryUrl(signalingUrl: string, limit: number, cursor?: number): string | null;
+/** 状态码与应答体 → 一页记录；出错抛 `RtcError`。 */
+export declare function parseCallHistory(status: number, body: unknown, limit: number): CallHistoryPage;
+/** 发请求并解析。`fetchImpl` 可注入，单测不碰网络。 */
+export declare function fetchCallHistory(signalingUrl: string, token: string, options?: FetchCallHistoryOptions, fetchImpl?: typeof fetch): Promise<CallHistoryPage>;
+//# sourceMappingURL=callHistory.d.ts.map

package/dist/callHistory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callHistory.d.ts","sourceRoot":"","sources":["../src/callHistory.ts"],"names":[],"mappings":"AAYA,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yBAAyB;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAChD;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,uBAAuB;IACtC,4BAA4B;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW/D;AAED,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMlG;AAoCD,qCAAqC;AACrC,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,CAgB9F;AAED,qCAAqC;AACrC,wBAAsB,gBAAgB,CACpC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,uBAA4B,EACrC,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,eAAe,CAAC,CAmB1B"}

package/dist/callHistory.js

@@ -0,0 +1,100 @@
+import { ErrorCode, RtcError } from './errors.js';
+/** 服务端每页上限（`maxCallLimit`）。超过它服务端也只回这么多，「到底」的判据就不成立了，所以本地先夹住。 */
+export const MAX_CALL_HISTORY_LIMIT = 200;
+export const DEFAULT_CALL_HISTORY_LIMIT = 20;
+/** 信令地址推出 REST 根：`ws→http`、`wss→https`，去掉末尾的 `/v1/ws`。推不出返回 `null`。 */
+export function restBaseUrl(signalingUrl) {
+    let url;
+    try {
+        url = new URL(signalingUrl);
+    }
+    catch {
+        return null;
+    }
+    const scheme = { 'ws:': 'http:', 'wss:': 'https:', 'http:': 'http:', 'https:': 'https:' }[url.protocol];
+    if (scheme === undefined)
+        return null;
+    const path = url.pathname.endsWith('/v1/ws') ? url.pathname.slice(0, -'/v1/ws'.length) : url.pathname;
+    return `${scheme}//${url.host}${path.replace(/\/$/, '')}`;
+}
+export function callHistoryUrl(signalingUrl, limit, cursor) {
+    const base = restBaseUrl(signalingUrl);
+    if (base === null)
+        return null;
+    const query = new URLSearchParams({ limit: String(limit) });
+    if (cursor !== undefined && cursor > 0)
+        query.set('cursor', String(cursor));
+    return `${base}/v1/calls?${query.toString()}`;
+}
+function str(o, key) {
+    const v = o[key];
+    return typeof v === 'string' ? v : '';
+}
+function num(o, key) {
+    const v = o[key];
+    return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function toRecord(o) {
+    const members = Array.isArray(o['members']) ? o['members'].filter(isObject) : [];
+    return {
+        callId: str(o, 'call_id'),
+        roomId: str(o, 'room_id'),
+        caller: str(o, 'caller'),
+        mediaType: str(o, 'media_type'),
+        isGroup: o['is_group'] === true,
+        reason: str(o, 'reason'),
+        endedBy: str(o, 'ended_by'),
+        durationSec: num(o, 'duration_sec'),
+        startedAtMs: num(o, 'started_at_ms'),
+        connectedAtMs: num(o, 'connected_at_ms'),
+        endedAtMs: num(o, 'ended_at_ms'),
+        userData: str(o, 'user_data'),
+        chatGroupId: str(o, 'chat_group_id'),
+        members: members.map((m) => ({ uid: str(m, 'uid'), state: str(m, 'state') })),
+    };
+}
+/** 状态码与应答体 → 一页记录；出错抛 `RtcError`。 */
+export function parseCallHistory(status, body, limit) {
+    if (status === 401) {
+        throw new RtcError(ErrorCode.tokenInvalid, { cause: new Error('查通话记录被拒（401）：票无效或已过期') });
+    }
+    if (status !== 200) {
+        throw new RtcError(ErrorCode.internal, { cause: new Error(`查通话记录失败：HTTP ${status}`) });
+    }
+    if (!isObject(body)) {
+        throw new RtcError(ErrorCode.internal, { cause: new Error('通话记录应答不是对象') });
+    }
+    const calls = Array.isArray(body['calls']) ? body['calls'].filter(isObject) : [];
+    const records = calls.map(toRecord);
+    const next = typeof body['next_cursor'] === 'number' ? body['next_cursor'] : null;
+    // 服务端只要这页有数据就给 next_cursor，没有「到底」标志：
+    // 不满一页就一定是最后一页，满页才交出游标（最坏多翻一页空的）。
+    return { records, nextCursor: records.length >= limit ? next : null };
+}
+/** 发请求并解析。`fetchImpl` 可注入，单测不碰网络。 */
+export async function fetchCallHistory(signalingUrl, token, options = {}, fetchImpl = fetch) {
+    const limit = Math.min(Math.max(Math.trunc(options.limit ?? DEFAULT_CALL_HISTORY_LIMIT), 1), MAX_CALL_HISTORY_LIMIT);
+    const url = callHistoryUrl(signalingUrl, limit, options.cursor);
+    if (url === null) {
+        throw new RtcError(ErrorCode.badParams, { cause: new Error(`信令地址无法推出 REST 地址：${signalingUrl}`) });
+    }
+    let response;
+    try {
+        response = await fetchImpl(url, { headers: { Authorization: `Bearer ${token}` } });
+    }
+    catch (err) {
+        throw new RtcError(ErrorCode.networkUnreachable, { cause: err });
+    }
+    let body = null;
+    try {
+        body = await response.json();
+    }
+    catch {
+        // 非 JSON：交给 parseCallHistory 按状态码报错。
+    }
+    return parseCallHistory(response.status, body, limit);
+}
+//# sourceMappingURL=callHistory.js.map

package/dist/callHistory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callHistory.js","sourceRoot":"","sources":["../src/callHistory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAuDlD,iEAAiE;AACjE,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAC1C,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,CAAC;AAE7C,uEAAuE;AACvE,MAAM,UAAU,WAAW,CAAC,YAAoB;IAC9C,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACxG,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC;IACtG,OAAO,GAAG,MAAM,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,YAAoB,EAAE,KAAa,EAAE,MAAe;IACjF,MAAM,IAAI,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;IACvC,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC5D,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5E,OAAO,GAAG,IAAI,aAAa,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC;AAChD,CAAC;AAED,SAAS,GAAG,CAAC,CAA0B,EAAE,GAAW;IAClD,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IACjB,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACxC,CAAC;AAED,SAAS,GAAG,CAAC,CAA0B,EAAE,GAAW;IAClD,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IACjB,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,QAAQ,CAAC,CAA0B;IAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACjF,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC;QACzB,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC;QACzB,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC;QACxB,SAAS,EAAE,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC;QAC/B,OAAO,EAAE,CAAC,CAAC,UAAU,CAAC,KAAK,IAAI;QAC/B,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC;QACxB,OAAO,EAAE,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC;QAC3B,WAAW,EAAE,GAAG,CAAC,CAAC,EAAE,cAAc,CAAC;QACnC,WAAW,EAAE,GAAG,CAAC,CAAC,EAAE,eAAe,CAAC;QACpC,aAAa,EAAE,GAAG,CAAC,CAAC,EAAE,iBAAiB,CAAC;QACxC,SAAS,EAAE,GAAG,CAAC,CAAC,EAAE,aAAa,CAAC;QAChC,QAAQ,EAAE,GAAG,CAAC,CAAC,EAAE,WAAW,CAAC;QAC7B,WAAW,EAAE,GAAG,CAAC,CAAC,EAAE,eAAe,CAAC;QACpC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;KAC9E,CAAC;AACJ,CAAC;AAED,qCAAqC;AACrC,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,IAAa,EAAE,KAAa;IAC3E,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,MAAM,IAAI,QAAQ,CAAC,SAAS,CAAC,YAAY,EAAE,EAAE,KAAK,EAAE,IAAI,KAAK,CAAC,sBAAsB,CAAC,EAAE,CAAC,CAAC;IAC3F,CAAC;IACD,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,MAAM,IAAI,QAAQ,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,KAAK,CAAC,gBAAgB,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,QAAQ,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACjF,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,aAAa,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAClF,qCAAqC;IACrC,kCAAkC;IAClC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACxE,CAAC;AAED,qCAAqC;AACrC,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,YAAoB,EACpB,KAAa,EACb,UAAmC,EAAE,EACrC,YAA0B,KAAK;IAE/B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,0BAA0B,CAAC,EAAE,CAAC,CAAC,EAAE,sBAAsB,CAAC,CAAC;IACrH,MAAM,GAAG,GAAG,cAAc,CAAC,YAAY,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,QAAQ,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,KAAK,CAAC,oBAAoB,YAAY,EAAE,CAAC,EAAE,CAAC,CAAC;IACpG,CAAC;IACD,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;IACrF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,QAAQ,CAAC,SAAS,CAAC,kBAAkB,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,IAAI,GAAY,IAAI,CAAC;IACzB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,qCAAqC;IACvC,CAAC;IACD,OAAO,gBAAgB,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;AACxD,CAAC"}

package/dist/callOptions.d.ts

@@ -1,3 +1,4 @@
+import type { MediaType } from './signaling/enums.js';
 /**
  * CallOptions 是 {@link CallEngine.call} 的可选项（HOST_INTEGRATION_DESIGN §3.3）。
  *
@@ -24,4 +25,17 @@ export interface CallOptions {
  * （`''` 表示宿主没给这个可选项）。
  */
 export declare function violatesCallOptionLimits(chatGroupId: string, userData: string): boolean;
+/** CallRequest 是 `call()` 整形之后的样子：状态机要的 `args`，外加本地校验要看的两个字段。 */
+export interface CallRequest {
+    readonly args: Record<string, unknown>;
+    readonly chatGroupId: string;
+    readonly userData: string;
+}
+/**
+ * toCallRequest 把 `call()` 的参数整形成状态机的 `act` 参数（snake_case）。
+ *
+ * `options` 传布尔值等同旧的 `isGroup`。**没给的可选项省略不写**，不写成空串——
+ * 省略表达「没传」，见 callMachine.ts startCall 的同一条注释。
+ */
+export declare function toCallRequest(calleeIds: string[], mediaType: MediaType, options?: boolean | CallOptions): CallRequest;
 //# sourceMappingURL=callOptions.d.ts.map

package/dist/callOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"callOptions.d.ts","sourceRoot":"","sources":["../src/callOptions.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAOD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKvF"}
+{"version":3,"file":"callOptions.d.ts","sourceRoot":"","sources":["../src/callOptions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAOD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKvF;AAED,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EAAE,EACnB,SAAS,EAAE,SAAS,EACpB,OAAO,CAAC,EAAE,OAAO,GAAG,WAAW,GAC9B,WAAW,CAWb"}

package/dist/callOptions.js

@@ -16,4 +16,25 @@ export function violatesCallOptionLimits(chatGroupId, userData) {
     }
     return byteLength(userData) > MAX_USER_DATA_BYTES;
 }
+/**
+ * toCallRequest 把 `call()` 的参数整形成状态机的 `act` 参数（snake_case）。
+ *
+ * `options` 传布尔值等同旧的 `isGroup`。**没给的可选项省略不写**，不写成空串——
+ * 省略表达「没传」，见 callMachine.ts startCall 的同一条注释。
+ */
+export function toCallRequest(calleeIds, mediaType, options) {
+    const opts = typeof options === 'boolean' ? { isGroup: options } : (options ?? {});
+    const chatGroupId = opts.chatGroupId ?? '';
+    const userData = opts.userData ?? '';
+    const args = {
+        callee_ids: calleeIds, media_type: mediaType, is_group: opts.isGroup ?? false,
+    };
+    if (chatGroupId !== '')
+        args['chat_group_id'] = chatGroupId;
+    if (userData !== '')
+        args['user_data'] = userData;
+    if (opts.timeoutSec !== undefined)
+        args['timeout_sec'] = opts.timeoutSec;
+    return { args, chatGroupId, userData };
+}
 //# sourceMappingURL=callOptions.js.map

package/dist/callOptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"callOptions.js","sourceRoot":"","sources":["../src/callOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAqBxC,mCAAmC;AACnC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AACnC,+BAA+B;AAC/B,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,WAAmB,EAAE,QAAgB;IAC5E,IAAI,WAAW,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,uBAAuB,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC;QACxG,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,UAAU,CAAC,QAAQ,CAAC,GAAG,mBAAmB,CAAC;AACpD,CAAC"}
+{"version":3,"file":"callOptions.js","sourceRoot":"","sources":["../src/callOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAsBxC,mCAAmC;AACnC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AACnC,+BAA+B;AAC/B,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,WAAmB,EAAE,QAAgB;IAC5E,IAAI,WAAW,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,uBAAuB,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC;QACxG,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,UAAU,CAAC,QAAQ,CAAC,GAAG,mBAAmB,CAAC;AACpD,CAAC;AASD;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,SAAmB,EACnB,SAAoB,EACpB,OAA+B;IAE/B,MAAM,IAAI,GAAgB,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;IAChG,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;IACrC,MAAM,IAAI,GAA4B;QACpC,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,CAAC,OAAO,IAAI,KAAK;KAC9E,CAAC;IACF,IAAI,WAAW,KAAK,EAAE;QAAE,IAAI,CAAC,eAAe,CAAC,GAAG,WAAW,CAAC;IAC5D,IAAI,QAAQ,KAAK,EAAE;QAAE,IAAI,CAAC,WAAW,CAAC,GAAG,QAAQ,CAAC;IAClD,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;QAAE,IAAI,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC;IACzE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;AACzC,CAAC"}

package/dist/debugToken.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 调试密钥本地签票（设计稿 `im-rtc-server/docs/design/DEBUG_KEY_DESIGN.md` §4）。
+ *
+ * **仅联调用**：把调试密钥放进客户端，等于把签票权交给所有拿到包的人。
+ * 上线必须换成宿主后端 `POST /v1/tokens`。服务端只认 kid 以 `dbg-` 开头的调试密钥。
+ * 向量：`im-rtc-server/docs/conformance/debug_token.json`。
+ */
+/** DebugTokenParams 是本地签票的入参。 */
+export interface DebugTokenParams {
+    readonly appId: string;
+    /** 调试密钥 id，必须以 `dbg-` 开头。 */
+    readonly keyId: string;
+    readonly secret: string;
+    readonly uid: string;
+    readonly deviceId?: string;
+    /** 有效期（秒）。缺省或 0 = 12h，钳到 [60, 2592000]（30 天）。 */
+    readonly ttlSec?: number;
+    /** 注入当前时间（Unix 毫秒），测试用；缺省 `Date.now()`。 */
+    readonly nowMs?: number;
+}
+/** hmacSha256B64url 返回 base64url(HMAC-SHA256(secret, input))，无填充。 */
+export declare function hmacSha256B64url(secret: string, input: string): Promise<string>;
+/**
+ * generateDebugToken 在本地用调试密钥签一张 HS256 JWT。**仅联调，上线换后端 `/v1/tokens`。**
+ *
+ * 入参不合法抛 `RtcError(1004)`。
+ */
+export declare function generateDebugToken(params: DebugTokenParams): Promise<string>;
+//# sourceMappingURL=debugToken.d.ts.map

package/dist/debugToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debugToken.d.ts","sourceRoot":"","sources":["../src/debugToken.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AAEH,iCAAiC;AACjC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAiBD,qEAAqE;AACrE,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAcrF;AAmBD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBlF"}

package/dist/debugToken.js

@@ -0,0 +1,73 @@
+import { byteLength } from './bytes.js';
+import { ErrorCode, RtcError } from './errors.js';
+import { logger } from './logger.js';
+const DEFAULT_TTL_SEC = 12 * 3600;
+const MIN_TTL_SEC = 60;
+const MAX_TTL_SEC = 30 * 24 * 3600;
+const MAX_UID_BYTES = 64;
+const ISSUER = 'im-rtc-server';
+const encoder = new TextEncoder();
+/** base64url 无填充。 */
+function b64url(bytes) {
+    let bin = '';
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/** hmacSha256B64url 返回 base64url(HMAC-SHA256(secret, input))，无填充。 */
+export async function hmacSha256B64url(secret, input) {
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle === undefined) {
+        // 非安全上下文（http 非 localhost）没有 crypto.subtle。
+        throw new RtcError(ErrorCode.internal, { cause: new Error('crypto.subtle 不可用（需 HTTPS 或 localhost）') });
+    }
+    const key = await subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return b64url(new Uint8Array(await subtle.sign('HMAC', key, encoder.encode(input))));
+}
+function validate(p) {
+    const bad = (why) => {
+        throw new RtcError(ErrorCode.badParams, { forType: `generateDebugToken: ${why}` });
+    };
+    if (p.appId === '')
+        bad('appId 为空');
+    if (p.secret === '')
+        bad('secret 为空');
+    if (!p.keyId.startsWith('dbg-'))
+        bad('keyId 必须以 dbg- 开头（不要把生产密钥放进客户端）');
+    if (p.uid === '')
+        bad('uid 为空');
+    if (/\s/u.test(p.uid))
+        bad('uid 含空白');
+    if (byteLength(p.uid) > MAX_UID_BYTES)
+        bad(`uid 超过 ${MAX_UID_BYTES} 字节`);
+}
+function clampTtl(ttlSec) {
+    if (ttlSec === undefined || ttlSec === 0 || !Number.isFinite(ttlSec))
+        return DEFAULT_TTL_SEC;
+    return Math.min(MAX_TTL_SEC, Math.max(MIN_TTL_SEC, Math.floor(ttlSec)));
+}
+/**
+ * generateDebugToken 在本地用调试密钥签一张 HS256 JWT。**仅联调，上线换后端 `/v1/tokens`。**
+ *
+ * 入参不合法抛 `RtcError(1004)`。
+ */
+export async function generateDebugToken(params) {
+    validate(params);
+    // 走 logger（默认 sink 即 console.warn；仓库禁止业务代码直接用 console）。
+    logger.warn('【仅联调】正在用调试密钥在客户端本地签票——上线必须换成后端 /v1/tokens，勿把密钥带进正式包');
+    const iat = Math.floor((params.nowMs ?? Date.now()) / 1000);
+    const claims = {
+        iss: ISSUER,
+        sub: params.uid,
+        aud: params.appId,
+        exp: iat + clampTtl(params.ttlSec),
+        iat,
+        scope: 'access',
+    };
+    if (params.deviceId !== undefined && params.deviceId !== '')
+        claims['did'] = params.deviceId;
+    const header = { alg: 'HS256', typ: 'JWT', kid: params.keyId };
+    const signingInput = `${b64url(encoder.encode(JSON.stringify(header)))}.${b64url(encoder.encode(JSON.stringify(claims)))}`;
+    return `${signingInput}.${await hmacSha256B64url(params.secret, signingInput)}`;
+}
+//# sourceMappingURL=debugToken.js.map

package/dist/debugToken.js.map

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