@ztlink-imk/ztlinkcloud-agent-sdk 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +93 -2
- package/dist/index.cjs +97 -0
- package/dist/index.d.cts +583 -0
- package/dist/index.d.ts +583 -0
- package/dist/index.js +74 -0
- package/package.json +29 -3
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,583 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 错误模型(public-api.d.ts「错误」一节)。
|
|
3
|
+
*
|
|
4
|
+
* 核心是 outcome:命令副作用是否已发生。调用方据此判断能否重试——
|
|
5
|
+
* not-sent 请求未发出,安全重试;rejected 服务端明确拒绝,无副作用;
|
|
6
|
+
* unknown 已发出但结果未知,不得假定未执行;local 纯本地命令。
|
|
7
|
+
* 错误对象与消息都已脱敏:不含 Token、密码、请求体和服务端原始报文。
|
|
8
|
+
*/
|
|
9
|
+
/** 后端契约错误码(http-contract.md §12) */
|
|
10
|
+
type ServerErrorCode = 'BAD_REQUEST' | 'VALIDATION_ERROR' | 'TOKEN_MISSING' | 'TOKEN_INVALID' | 'TOKEN_EXPIRED' | 'SESSION_REVOKED' | 'SESSION_EXPIRED' | 'TICKET_INVALID' | 'TICKET_EXPIRED' | 'TICKET_USED' | 'REFRESH_TOKEN_INVALID' | 'REFRESH_TOKEN_REPLAYED' | 'REFRESH_NOT_COMMITTED' | 'PERMISSION_DENIED' | 'APP_DISABLED' | 'AGENT_DISABLED' | 'AGENT_NOT_FOUND' | 'AGENT_ALREADY_EXISTS' | 'CALL_CONTROL_REJECTED' | 'AGENT_SIP_NOT_READY' | 'AGENT_CONFLICT' | 'RATE_LIMITED' | 'INTERNAL_ERROR' | 'PROVIDER_BAD_RESPONSE' | 'SERVICE_UNAVAILABLE' | 'SIP_CREDENTIAL_UNAVAILABLE' | 'PROVIDER_TIMEOUT' | 'NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'UNSUPPORTED_MEDIA_TYPE';
|
|
11
|
+
/** SDK 本地错误码 */
|
|
12
|
+
type SdkErrorCode = 'DESTROYED' | 'NOT_INITIALIZED' | 'ALREADY_INITIALIZED' | 'INITIALIZE_IN_PROGRESS' | 'INITIALIZE_FAILED' | 'NOT_AUTHENTICATED' | 'COMMAND_IN_PROGRESS' | 'NOT_REGISTERED' | 'REGISTRATION_FAILED' | 'SIGNALING_UNAVAILABLE' | 'INVALID_NUMBER' | 'INVALID_ARGUMENT' | 'CALL_IN_PROGRESS' | 'CALL_NOT_FOUND' | 'INVALID_CALL_STATE' | 'CALL_STATE_CHANGED' | 'CALL_STATE_UNKNOWN' | 'CALL_ENDED' | 'HOLD_TRANSITION_IN_PROGRESS' | 'HOLD_FAILED' | 'HOLD_TIMEOUT' | 'MEDIA_PERMISSION_DENIED' | 'MEDIA_DEVICE_UNAVAILABLE' | 'NETWORK_ERROR' | 'TIMEOUT' | 'ABORTED';
|
|
13
|
+
type ErrorCode = ServerErrorCode | SdkErrorCode;
|
|
14
|
+
/** 错误来源 */
|
|
15
|
+
type ErrorKind = 'http' | 'network' | 'timeout' | 'aborted' | 'state' | 'sip' | 'media' | 'argument';
|
|
16
|
+
/** 命令副作用是否已发生 */
|
|
17
|
+
type CommandOutcome = 'not-sent' | 'rejected' | 'unknown' | 'local';
|
|
18
|
+
/** 可序列化的错误信息,存在于状态与事件中 */
|
|
19
|
+
interface CallCenterErrorInfo {
|
|
20
|
+
readonly kind: ErrorKind;
|
|
21
|
+
readonly code: ErrorCode;
|
|
22
|
+
readonly retryable: boolean;
|
|
23
|
+
readonly outcome: CommandOutcome;
|
|
24
|
+
readonly httpStatus?: number;
|
|
25
|
+
readonly retryAfterSeconds?: number;
|
|
26
|
+
/** 不含 Token、密码、号码、原始服务端报文 */
|
|
27
|
+
readonly message: string;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* 公共状态与事件类型。权威定义是 docs/call-center/public-api.d.ts(P-04 已验收),
|
|
32
|
+
* 本文件只复制本包已实现部分;test/unit/conformance.test.ts 用类型断言保证两边一致。
|
|
33
|
+
*/
|
|
34
|
+
|
|
35
|
+
/** 取消订阅函数;重复调用无副作用 */
|
|
36
|
+
type Unsubscribe = () => void;
|
|
37
|
+
/** UTC RFC3339 时间字符串,以 Z 结尾 */
|
|
38
|
+
type IsoDateTime = string;
|
|
39
|
+
interface DeviceInfo {
|
|
40
|
+
readonly deviceId?: string;
|
|
41
|
+
readonly deviceLabel?: string;
|
|
42
|
+
}
|
|
43
|
+
/** 脱敏诊断条目:不含 Token、SIP 密码、号码、联系人展示信息 */
|
|
44
|
+
interface DiagnosticEntry {
|
|
45
|
+
readonly level: 'debug' | 'info' | 'warn' | 'error';
|
|
46
|
+
readonly area: 'auth' | 'http' | 'registration' | 'call' | 'media';
|
|
47
|
+
readonly code: string;
|
|
48
|
+
readonly at: number;
|
|
49
|
+
}
|
|
50
|
+
interface CallCenterOptions {
|
|
51
|
+
readonly apiBaseUrl: string;
|
|
52
|
+
/** 业务通知 WS 地址(ws/wss);不传则不建立通知连接,SIP 与 HTTP 行为不变。 */
|
|
53
|
+
readonly wsUrl?: string;
|
|
54
|
+
readonly device?: DeviceInfo;
|
|
55
|
+
readonly requestTimeoutMs?: number;
|
|
56
|
+
readonly signalingLossGraceMs?: number;
|
|
57
|
+
readonly iceServers?: readonly RTCIceServer[];
|
|
58
|
+
readonly onDiagnostic?: (entry: DiagnosticEntry) => void;
|
|
59
|
+
}
|
|
60
|
+
interface ClientIdentity {
|
|
61
|
+
readonly appId: string;
|
|
62
|
+
readonly agentId: string;
|
|
63
|
+
readonly clientSessionId: string;
|
|
64
|
+
}
|
|
65
|
+
type UnauthenticatedReason = 'initial' | 'logged-out' | 'login-failed' | 'init-failed' | 'session-revoked' | 'session-expired' | 'agent-disabled' | 'app-disabled' | 'refresh-failed';
|
|
66
|
+
/** 注销请求的服务端结果;业务认证撤销不表示 SIP 通话已结束 */
|
|
67
|
+
type LogoutSettlement = {
|
|
68
|
+
readonly status: 'confirmed';
|
|
69
|
+
} | {
|
|
70
|
+
readonly status: 'unconfirmed';
|
|
71
|
+
};
|
|
72
|
+
type AuthState = {
|
|
73
|
+
readonly status: 'unauthenticated';
|
|
74
|
+
readonly reason: UnauthenticatedReason;
|
|
75
|
+
readonly logout?: LogoutSettlement;
|
|
76
|
+
} | {
|
|
77
|
+
readonly status: 'authenticating';
|
|
78
|
+
} | {
|
|
79
|
+
readonly status: 'authenticated';
|
|
80
|
+
readonly identity: ClientIdentity;
|
|
81
|
+
readonly accessExpiresAt: IsoDateTime;
|
|
82
|
+
readonly sessionExpiresAt: IsoDateTime;
|
|
83
|
+
} | {
|
|
84
|
+
readonly status: 'logging-out';
|
|
85
|
+
};
|
|
86
|
+
interface AgentProfile {
|
|
87
|
+
readonly agentId: string;
|
|
88
|
+
readonly externalAgentId: string;
|
|
89
|
+
readonly displayName: string;
|
|
90
|
+
}
|
|
91
|
+
type RegistrationState = {
|
|
92
|
+
readonly status: 'unregistered';
|
|
93
|
+
} | {
|
|
94
|
+
readonly status: 'registering';
|
|
95
|
+
} | {
|
|
96
|
+
readonly status: 'registered';
|
|
97
|
+
} | {
|
|
98
|
+
readonly status: 'unregistering';
|
|
99
|
+
} | {
|
|
100
|
+
readonly status: 'failed';
|
|
101
|
+
readonly error: CallCenterErrorInfo;
|
|
102
|
+
};
|
|
103
|
+
/** 当前坐席注册入口;同实例并发共享在途结果,失败 reject 并保留脱敏状态。 */
|
|
104
|
+
interface RegistrationApi {
|
|
105
|
+
/** 读取真实登录参数并等待 SIP 注册结果,不自动拨号。 */
|
|
106
|
+
register(): Promise<RegistrationState>;
|
|
107
|
+
}
|
|
108
|
+
interface ConnectionState {
|
|
109
|
+
readonly status: 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
|
|
110
|
+
}
|
|
111
|
+
type CallStatus = 'connecting' | 'ringing' | 'incoming' | 'answering' | 'connected' | 'ending' | 'ended' | 'unknown';
|
|
112
|
+
type CallEndReason = 'local-hangup' | 'remote-hangup' | 'cancelled' | 'rejected-local' | 'rejected-remote' | 'busy' | 'unanswered' | 'revoked' | 'failed' | 'transport-lost';
|
|
113
|
+
type LocalHoldState = 'off' | 'requesting' | 'on' | 'releasing';
|
|
114
|
+
interface CallDisplay {
|
|
115
|
+
readonly contactName?: string;
|
|
116
|
+
readonly location?: string;
|
|
117
|
+
readonly note?: string;
|
|
118
|
+
}
|
|
119
|
+
interface CallSnapshot {
|
|
120
|
+
readonly callId: string;
|
|
121
|
+
readonly direction: 'outbound' | 'inbound';
|
|
122
|
+
readonly status: CallStatus;
|
|
123
|
+
/** 外呼为目标号码,回呼为 INVITE 的 anumber。 */
|
|
124
|
+
readonly remoteNumber: string;
|
|
125
|
+
/** 回呼原始号码;三个请求头全部校验完成后才随来电快照发布,不受 setDisplay 修改影响。 */
|
|
126
|
+
readonly callbackNumbers?: {
|
|
127
|
+
/** 来电主号码。 */
|
|
128
|
+
readonly anumber: string;
|
|
129
|
+
/** 被叫号码。 */
|
|
130
|
+
readonly bnumber: string;
|
|
131
|
+
/** 外显号码。 */
|
|
132
|
+
readonly xnumber: string;
|
|
133
|
+
};
|
|
134
|
+
readonly display?: CallDisplay;
|
|
135
|
+
/**
|
|
136
|
+
* 外呼经 AXB 分配的外显号码(WS-10):仅当业务通知的 bnumber 与本次拨打号码完全一致时写入,
|
|
137
|
+
* 来电与未匹配的外呼不携带;更新通过同状态 call.status 发布,不改变通话状态。
|
|
138
|
+
*/
|
|
139
|
+
readonly xnumber?: string;
|
|
140
|
+
/** 外呼 X 号码归属省区;仅省市齐全时随号码写入;同号后续缺失保留,换号且无省市时清除。 */
|
|
141
|
+
readonly xprovince?: string;
|
|
142
|
+
/** 外呼 X 号码归属城市;与 xprovince 成对出现。 */
|
|
143
|
+
readonly xcity?: string;
|
|
144
|
+
/** 合法 FS 标识且 connected 时 ready;标识不公开。 */
|
|
145
|
+
readonly callControl: 'ready' | 'unavailable';
|
|
146
|
+
readonly muted: boolean;
|
|
147
|
+
readonly localHold: LocalHoldState;
|
|
148
|
+
readonly remoteHold: boolean;
|
|
149
|
+
readonly signaling: 'ok' | 'lost';
|
|
150
|
+
readonly peerAnswered: 'unknown' | 'confirmed' | 'not-applicable';
|
|
151
|
+
readonly createdAt: number;
|
|
152
|
+
readonly connectedAt?: number;
|
|
153
|
+
readonly endedAt?: number;
|
|
154
|
+
readonly endReason?: CallEndReason;
|
|
155
|
+
/**
|
|
156
|
+
* 外呼收到 FS 最终拒绝时的 SIP 状态码(如 403/404 账号无效、486/603 业务拒绝),与 endReason 一起随 call.ended 给出;
|
|
157
|
+
* 仅在该拒绝决定结束原因时出现,来电、本地取消/挂断及其他结束不携带。
|
|
158
|
+
*/
|
|
159
|
+
readonly sipStatus?: number;
|
|
160
|
+
}
|
|
161
|
+
/** 外呼可选展示信息,不作为号码路由或客户接听证据。 */
|
|
162
|
+
interface DialOptions {
|
|
163
|
+
readonly display?: CallDisplay;
|
|
164
|
+
}
|
|
165
|
+
/** 一键拨打只等待当前在途准备,不领取 Ticket 或发起注册。 */
|
|
166
|
+
interface QuickDialOptions {
|
|
167
|
+
readonly display?: CallDisplay;
|
|
168
|
+
/** 认证中、登录连接材料 加载或注册中的等待上限,默认 10000 毫秒。 */
|
|
169
|
+
readonly waitMs?: number;
|
|
170
|
+
}
|
|
171
|
+
type QuickDialBlockedReason = 'not-authenticated' | 'registration-failed' | 'call-in-progress' | 'wait-timeout';
|
|
172
|
+
/** 稳定资格不足返回 blocked;实际拨打命令失败保留原错误。 */
|
|
173
|
+
type QuickDialOutcome = {
|
|
174
|
+
readonly status: 'started';
|
|
175
|
+
readonly call: CallSnapshot;
|
|
176
|
+
} | {
|
|
177
|
+
readonly status: 'blocked';
|
|
178
|
+
readonly reason: QuickDialBlockedReason;
|
|
179
|
+
};
|
|
180
|
+
/** 单 Core 的真实 SIP 通话入口;命令结果不代表客户业务腿接听。 */
|
|
181
|
+
interface CallApi {
|
|
182
|
+
/** 发起一次外呼,返回建立中快照,不等待接通。 */
|
|
183
|
+
dial(number: string, options?: DialOptions): Promise<CallSnapshot>;
|
|
184
|
+
/** 接听当前来电,等待会话建立。 */
|
|
185
|
+
accept(callId: string): Promise<CallSnapshot>;
|
|
186
|
+
/** 拒绝尚未接听的来电。 */
|
|
187
|
+
reject(callId: string): Promise<CallSnapshot>;
|
|
188
|
+
/** 取消尚未建立的外呼,竞争成功由 SIP.js ACK/BYE 收敛。 */
|
|
189
|
+
cancel(callId: string): Promise<CallSnapshot>;
|
|
190
|
+
/** 挂断已建立会话;业务认证失效后仍可调用。 */
|
|
191
|
+
hangup(callId: string): Promise<CallSnapshot>;
|
|
192
|
+
/** 已认证、connected 且 callControl=ready 时调用 FS;HTTP 200 后更新 muted,失败 reject。 */
|
|
193
|
+
mute(callId: string): Promise<CallSnapshot>;
|
|
194
|
+
/** 与 mute 相同前置条件,HTTP 200 后取消 FS 静音,不改变保持状态。 */
|
|
195
|
+
unmute(callId: string): Promise<CallSnapshot>;
|
|
196
|
+
/** 等待 HTTP 200 确认后进入保持。 */
|
|
197
|
+
hold(callId: string): Promise<CallSnapshot>;
|
|
198
|
+
/** 等待 HTTP 200 确认后恢复,保留静音。 */
|
|
199
|
+
unhold(callId: string): Promise<CallSnapshot>;
|
|
200
|
+
/** 同步更新当前通话展示,不发请求。 */
|
|
201
|
+
setDisplay(callId: string, display: CallDisplay): CallSnapshot;
|
|
202
|
+
}
|
|
203
|
+
interface AudioDeviceInfo {
|
|
204
|
+
readonly deviceId: string;
|
|
205
|
+
readonly label: string;
|
|
206
|
+
}
|
|
207
|
+
interface DevicesState {
|
|
208
|
+
readonly permission: 'unknown' | 'prompt' | 'granted' | 'denied' | 'unavailable';
|
|
209
|
+
readonly inputs: readonly AudioDeviceInfo[];
|
|
210
|
+
readonly outputs: readonly AudioDeviceInfo[];
|
|
211
|
+
readonly selectedInputId: string | null;
|
|
212
|
+
readonly selectedOutputId: string | null;
|
|
213
|
+
readonly outputSelectionSupported: boolean;
|
|
214
|
+
readonly playbackBlocked: boolean;
|
|
215
|
+
}
|
|
216
|
+
/** 设备行为遵循既有公共合同;查询、授权与实际通话切换由 Core 管理。 */
|
|
217
|
+
interface DevicesApi {
|
|
218
|
+
/** 只读枚举和权限查询,不为标签采集。 */
|
|
219
|
+
refresh(): Promise<DevicesState>;
|
|
220
|
+
/** 显式授权,探测流立即停止;活动通话复用实际采集。 */
|
|
221
|
+
requestPermission(): Promise<DevicesState>;
|
|
222
|
+
/** null 使用系统默认;活动切换保留 muted 和 localHold。 */
|
|
223
|
+
selectInput(deviceId: string | null): Promise<DevicesState>;
|
|
224
|
+
/** 运行时支持时选择真实输出,无通话时只保存偏好。 */
|
|
225
|
+
selectOutput(deviceId: string | null): Promise<DevicesState>;
|
|
226
|
+
/** 用户手势中恢复远端音频播放。 */
|
|
227
|
+
resumePlayback(): Promise<void>;
|
|
228
|
+
}
|
|
229
|
+
type DialBlockReason = 'not-authenticated' | 'not-registered' | 'signaling-unavailable' | 'call-in-progress';
|
|
230
|
+
type Dialability = {
|
|
231
|
+
readonly allowed: true;
|
|
232
|
+
} | {
|
|
233
|
+
readonly allowed: false;
|
|
234
|
+
readonly reason: DialBlockReason;
|
|
235
|
+
};
|
|
236
|
+
/** 坐席示闲/示忙意图:READY 示闲,NOT_READY 示忙。 */
|
|
237
|
+
type WorkStatusValue = 'READY' | 'NOT_READY';
|
|
238
|
+
/** 示忙原因:MANUAL 坐席手动,MISSED 回呼未接后由服务端自动示忙(需坐席手动示闲)。 */
|
|
239
|
+
type WorkStatusReason = 'MANUAL' | 'MISSED';
|
|
240
|
+
/** 服务端确认的示闲/示忙;只反映坐席意图,不代表 SIP 在线或可接听。 */
|
|
241
|
+
interface WorkStatus {
|
|
242
|
+
readonly status: WorkStatusValue;
|
|
243
|
+
/** 示闲或从未写入时为 null。 */
|
|
244
|
+
readonly reason: WorkStatusReason | null;
|
|
245
|
+
/** 服务端变更时刻(通知推送时为推送时刻);从未写入为 null。 */
|
|
246
|
+
readonly at: IsoDateTime | null;
|
|
247
|
+
}
|
|
248
|
+
interface CallCenterState {
|
|
249
|
+
readonly lifecycle: 'active' | 'destroyed';
|
|
250
|
+
readonly auth: AuthState;
|
|
251
|
+
readonly agent: AgentProfile | null;
|
|
252
|
+
readonly telephony: {
|
|
253
|
+
readonly wssUrl: string;
|
|
254
|
+
readonly realm: string;
|
|
255
|
+
} | null;
|
|
256
|
+
readonly registration: RegistrationState;
|
|
257
|
+
readonly connection: ConnectionState;
|
|
258
|
+
readonly call: CallSnapshot | null;
|
|
259
|
+
readonly devices: DevicesState;
|
|
260
|
+
readonly dialability: Dialability;
|
|
261
|
+
/** 当前业务会话的示闲/示忙;未认证或尚未从服务端取得时为 null。 */
|
|
262
|
+
readonly workStatus: WorkStatus | null;
|
|
263
|
+
}
|
|
264
|
+
type BackgroundPhase = 'refresh' | 'credentials' | 'registration' | 'signaling' | 'media';
|
|
265
|
+
/** 通知事件类型:来源上报的三种事件原名,及 AXB 回调晚于振铃时单独推送的 AXB_BOUND。 */
|
|
266
|
+
type NotificationEventType = 'CALL_RINGING' | 'CALL_ANSWERED' | 'EventCallCDR' | 'AXB_BOUND';
|
|
267
|
+
/** 通知数据的来源形状:可选 X/B 号码与成对省市;xnumber 缺失与显式 null 是两种不同事实。 */
|
|
268
|
+
interface NotificationEventData {
|
|
269
|
+
/** 来源号码;缺失时不出现,null 与空串原样保留,不补值、不推断。 */
|
|
270
|
+
readonly xnumber?: string | null;
|
|
271
|
+
/** AXB 回调 B 号;仅号码来自回调时出现,供匹配当前外呼的拨打号码。 */
|
|
272
|
+
readonly bnumber?: string;
|
|
273
|
+
/** X 号码归属省区;非空字符串,≤32 字符,省市任一非法或缺失时两项一起省略。 */
|
|
274
|
+
readonly xprovince?: string;
|
|
275
|
+
/** X 号码归属城市;与 xprovince 成对出现。 */
|
|
276
|
+
readonly xcity?: string;
|
|
277
|
+
}
|
|
278
|
+
/**
|
|
279
|
+
* 独立业务通知的来源投影(WS-01 契约补充 §3)。
|
|
280
|
+
*
|
|
281
|
+
* 它与 SIP 通话事实无关:sessionID 只是宿主业务关联标识,不是 SIP Call-ID 或 SDK callId;
|
|
282
|
+
* 重复、丢失和乱序都不被转换成权威通话状态,也不改写 call.status/call.ended。
|
|
283
|
+
*/
|
|
284
|
+
interface NotificationEvent {
|
|
285
|
+
/** 固定协议版本 1 */
|
|
286
|
+
readonly version: 1;
|
|
287
|
+
/** 来源为每次通知生成的唯一标识;不用于去重或排序 */
|
|
288
|
+
readonly eventId: string;
|
|
289
|
+
/** 来源话单唯一标识,原样保留为宿主关联键 */
|
|
290
|
+
readonly sessionID: string;
|
|
291
|
+
/** 固定主题 */
|
|
292
|
+
readonly topic: 'call';
|
|
293
|
+
/** 来源上报的事件名 */
|
|
294
|
+
readonly eventType: NotificationEventType;
|
|
295
|
+
/** 来源确认接收成功时的 UTC 毫秒时刻,不保证源业务顺序 */
|
|
296
|
+
readonly occurredAt: IsoDateTime;
|
|
297
|
+
/** 可选号码段;来源未给出时整段缺失 */
|
|
298
|
+
readonly data?: NotificationEventData;
|
|
299
|
+
}
|
|
300
|
+
interface CallCenterEventMap {
|
|
301
|
+
'auth.authenticated': {
|
|
302
|
+
identity: ClientIdentity;
|
|
303
|
+
sessionExpiresAt: IsoDateTime;
|
|
304
|
+
};
|
|
305
|
+
'auth.refreshed': {
|
|
306
|
+
accessExpiresAt: IsoDateTime;
|
|
307
|
+
};
|
|
308
|
+
'auth.unauthenticated': {
|
|
309
|
+
reason: UnauthenticatedReason;
|
|
310
|
+
logout?: LogoutSettlement;
|
|
311
|
+
};
|
|
312
|
+
'registration.changed': {
|
|
313
|
+
registration: RegistrationState;
|
|
314
|
+
};
|
|
315
|
+
'connection.changed': {
|
|
316
|
+
connection: ConnectionState;
|
|
317
|
+
};
|
|
318
|
+
'call.incoming': {
|
|
319
|
+
call: CallSnapshot;
|
|
320
|
+
};
|
|
321
|
+
'call.incoming-dropped': {
|
|
322
|
+
reason: 'busy' | 'not-eligible';
|
|
323
|
+
};
|
|
324
|
+
'call.status': {
|
|
325
|
+
call: CallSnapshot;
|
|
326
|
+
previous: CallStatus;
|
|
327
|
+
};
|
|
328
|
+
'call.media': {
|
|
329
|
+
call: CallSnapshot;
|
|
330
|
+
changed: readonly ('muted' | 'localHold' | 'remoteHold')[];
|
|
331
|
+
};
|
|
332
|
+
'call.hold-failed': {
|
|
333
|
+
callId: string;
|
|
334
|
+
action: 'hold' | 'unhold';
|
|
335
|
+
error: CallCenterErrorInfo;
|
|
336
|
+
};
|
|
337
|
+
'call.ended': {
|
|
338
|
+
call: CallSnapshot;
|
|
339
|
+
};
|
|
340
|
+
'devices.changed': {
|
|
341
|
+
devices: DevicesState;
|
|
342
|
+
};
|
|
343
|
+
'media.playback-blocked': {
|
|
344
|
+
callId: string;
|
|
345
|
+
};
|
|
346
|
+
/** 独立通知通道收到的来源事件;不影响 SIP 通话快照或媒体资源。 */
|
|
347
|
+
'notification.received': {
|
|
348
|
+
notification: NotificationEvent;
|
|
349
|
+
};
|
|
350
|
+
/** 示闲/示忙快照已更新(设置成功、服务端通知或重连补齐)。 */
|
|
351
|
+
'work-status.changed': {
|
|
352
|
+
workStatus: WorkStatus;
|
|
353
|
+
};
|
|
354
|
+
/** 刚进入 MISSED 自动示忙,紧随 work-status.changed;宿主据此提示坐席手动示闲。 */
|
|
355
|
+
'work-status.missed': {
|
|
356
|
+
workStatus: WorkStatus;
|
|
357
|
+
};
|
|
358
|
+
'sdk.error': {
|
|
359
|
+
phase: BackgroundPhase;
|
|
360
|
+
error: CallCenterErrorInfo;
|
|
361
|
+
};
|
|
362
|
+
}
|
|
363
|
+
type CallCenterEventType = keyof CallCenterEventMap;
|
|
364
|
+
/** 所有事件共有:seq 为实例内严格递增序号,at 为本地时钟 ms */
|
|
365
|
+
type CallCenterEvent = {
|
|
366
|
+
[K in CallCenterEventType]: {
|
|
367
|
+
readonly type: K;
|
|
368
|
+
readonly seq: number;
|
|
369
|
+
readonly at: number;
|
|
370
|
+
} & CallCenterEventMap[K];
|
|
371
|
+
}[CallCenterEventType];
|
|
372
|
+
interface InitializeResult {
|
|
373
|
+
readonly auth: Extract<AuthState, {
|
|
374
|
+
status: 'authenticated';
|
|
375
|
+
}>;
|
|
376
|
+
readonly agent: AgentProfile;
|
|
377
|
+
readonly telephony: {
|
|
378
|
+
readonly wssUrl: string;
|
|
379
|
+
readonly realm: string;
|
|
380
|
+
};
|
|
381
|
+
}
|
|
382
|
+
interface LogoutResult {
|
|
383
|
+
readonly local: 'logged-out';
|
|
384
|
+
readonly server: LogoutSettlement | {
|
|
385
|
+
readonly status: 'not-required';
|
|
386
|
+
};
|
|
387
|
+
}
|
|
388
|
+
interface DestroyOptions {
|
|
389
|
+
readonly terminateActiveCall?: boolean;
|
|
390
|
+
}
|
|
391
|
+
/** 坐席人员分类,仅分类,不用于推导当前用户的管理权限。 */
|
|
392
|
+
type AgentCategory = 'agent' | 'manager' | 'qc' | 'store_admin';
|
|
393
|
+
/** 管理接口公开坐席资源;SIP就绪与业务启停分别表达。 */
|
|
394
|
+
interface AgentResource extends AgentProfile {
|
|
395
|
+
readonly status: 'ENABLED' | 'DISABLED';
|
|
396
|
+
readonly telephonyStatus: 'PENDING' | 'READY' | 'FAILED' | 'NOT_BOUND';
|
|
397
|
+
}
|
|
398
|
+
/** 创建资料由调用方提供,可选项不由SDK补默认值。 */
|
|
399
|
+
interface CreateAgentInput {
|
|
400
|
+
/** 外部工号,1~32位字母/数字/下划线/短横线。 */
|
|
401
|
+
readonly externalAgentId: string;
|
|
402
|
+
/** 姓名,最长50字符。 */
|
|
403
|
+
readonly displayName: string;
|
|
404
|
+
/** 所属门店S码;未传时由外部接口校验。 */
|
|
405
|
+
readonly scode?: string | null;
|
|
406
|
+
/** 11位大陆手机号;未传时由外部接口校验。 */
|
|
407
|
+
readonly mobile?: string | null;
|
|
408
|
+
/** 人员类型;未传时由外部接口校验。 */
|
|
409
|
+
readonly type?: AgentCategory | null;
|
|
410
|
+
}
|
|
411
|
+
/** 局部更新,未传或null保留原值;至少提供一项非null,不改工号、门店、SIP凭据。 */
|
|
412
|
+
interface UpdateAgentInput {
|
|
413
|
+
readonly displayName?: string | null;
|
|
414
|
+
readonly mobile?: string | null;
|
|
415
|
+
readonly type?: AgentCategory | null;
|
|
416
|
+
/** 0禁用、1启用、2锁定。 */
|
|
417
|
+
readonly status?: 0 | 1 | 2 | null;
|
|
418
|
+
}
|
|
419
|
+
/** 管理当前登录应用的坐席;应用获对应权限后,该应用下所有有效登录坐席均可操作。 */
|
|
420
|
+
interface AgentsApi {
|
|
421
|
+
/** 创建档案;工号已存在返回 AGENT_ALREADY_EXISTS,未知结果不自动重发,应查询原工号。 */
|
|
422
|
+
create(input: CreateAgentInput): Promise<AgentResource>;
|
|
423
|
+
/** 查询当前应用内坐席,不接收appId。 */
|
|
424
|
+
get(agentId: string): Promise<AgentResource>;
|
|
425
|
+
/** 修改调用方明确提供的资料,成功不更换当前登录会话。 */
|
|
426
|
+
update(agentId: string, input: UpdateAgentInput): Promise<AgentResource>;
|
|
427
|
+
/** 仅禁用状态,保留档案及其他资料;停用当前登录坐席后后续准入会拒绝。 */
|
|
428
|
+
disable(agentId: string): Promise<AgentResource>;
|
|
429
|
+
}
|
|
430
|
+
/** 本 SDK 消费的后端 HTTP 契约版本(openapi-v1.yaml info.version) */
|
|
431
|
+
declare const CONTRACT_VERSION: "0.15.0";
|
|
432
|
+
|
|
433
|
+
/** 宿主稳定门面;仅描述已验收能力,不从内部实现推导额外类型。 */
|
|
434
|
+
interface CallCenter {
|
|
435
|
+
/** 使用当前登录Token管理本应用坐席,按应用权限授权。 */
|
|
436
|
+
readonly agents: AgentsApi;
|
|
437
|
+
/** 当前运行时版本;同一大版本内由服务端下发,取值随发布变化,类型不随版本变化。 */
|
|
438
|
+
readonly sdkVersion: string;
|
|
439
|
+
/** 当前 HTTP 契约版本。 */
|
|
440
|
+
readonly contractVersion: typeof CONTRACT_VERSION;
|
|
441
|
+
/** 兑换一次性 Ticket,依次确认身份和配置;认证失败 reject,配置分阶段返回。 */
|
|
442
|
+
initialize(ticket: string): Promise<InitializeResult>;
|
|
443
|
+
/** 仅重试 unavailable 配置,不重新登录。 */
|
|
444
|
+
/** 有界等待当前准备并拨打一次,不取票、不注册、不重拨。 */
|
|
445
|
+
quickDial(number: string, options?: QuickDialOptions): Promise<QuickDialOutcome>;
|
|
446
|
+
/** 当前唯一电话的命令。 */
|
|
447
|
+
readonly call: CallApi;
|
|
448
|
+
/** 独立设备与权限入口。 */
|
|
449
|
+
readonly devices: DevicesApi;
|
|
450
|
+
/** 显式注册入口,不自动拨号。 */
|
|
451
|
+
readonly registration: RegistrationApi;
|
|
452
|
+
/**
|
|
453
|
+
* 设置示闲/示忙(PUT /client/v1/agent/work-status);HTTP 200 后更新 workStatus 并派发 work-status.changed。
|
|
454
|
+
* 失败 reject 且快照不变;坐席未绑定 SIP 为 AGENT_SIP_NOT_READY。登录默认示闲由服务端写入,SDK 不自行设置。
|
|
455
|
+
*/
|
|
456
|
+
setWorkStatus(status: WorkStatusValue): Promise<WorkStatus>;
|
|
457
|
+
/** 本地立即清密,服务端结果独立结算。 */
|
|
458
|
+
logout(): Promise<LogoutResult>;
|
|
459
|
+
/** 重复调用单飞;默认保护活动电话,释放失败 reject。 */
|
|
460
|
+
destroy(options?: DestroyOptions): Promise<void>;
|
|
461
|
+
/** 读取当前事实并复核期限,不从本地状态恢复授权。 */
|
|
462
|
+
getState(): CallCenterState;
|
|
463
|
+
/** 状态先更新再通知;返回可重复执行的取消函数。 */
|
|
464
|
+
subscribe(listener: (event: CallCenterEvent) => void): Unsubscribe;
|
|
465
|
+
/** 订阅指定事件;宿主回调异常不影响其他订阅者。 */
|
|
466
|
+
on<K extends CallCenterEventType>(type: K, handler: (event: Extract<CallCenterEvent, {
|
|
467
|
+
type: K;
|
|
468
|
+
}>) => void): Unsubscribe;
|
|
469
|
+
}
|
|
470
|
+
|
|
471
|
+
/**
|
|
472
|
+
* 运行时公共合同:window.ImkAgentSdk 的形状。运行时(packages/runtime)按此实现,
|
|
473
|
+
* 加载器按此返回;同一大版本内只允许向后兼容的新增,不删除、不改名、不改语义。
|
|
474
|
+
*/
|
|
475
|
+
|
|
476
|
+
/** 服务端随 Ticket 下发的 SDK 信息(Ticket 响应 data.sdk),宿主原样交给加载器。 */
|
|
477
|
+
interface SdkDelivery {
|
|
478
|
+
/** 运行时完整版本号,如 1.2.3。 */
|
|
479
|
+
readonly version: string;
|
|
480
|
+
/** 带 CDN 签名的运行时地址;不含 Ticket,签名有效期有限,需用本次签发的值。 */
|
|
481
|
+
readonly url: string;
|
|
482
|
+
/** 运行时文件的 SRI 值(sha384-...),浏览器据此校验下载内容。 */
|
|
483
|
+
readonly integrity: string;
|
|
484
|
+
}
|
|
485
|
+
/** mountPanel 选项。 */
|
|
486
|
+
interface PanelOptions {
|
|
487
|
+
/** 宿主创建的唯一 Core 实例;面板只订阅和调用,不销毁。 */
|
|
488
|
+
readonly core: CallCenter;
|
|
489
|
+
/** 挂载时是否展开,默认展开;挂载后用 open/close 控制。 */
|
|
490
|
+
readonly initiallyVisible?: boolean;
|
|
491
|
+
/** 宿主可选展示的联系人名称,不参与通话资格判断。 */
|
|
492
|
+
readonly contactName?: string;
|
|
493
|
+
/** 宿主可选展示的补充说明,不参与通话资格判断。 */
|
|
494
|
+
readonly supplementaryInfo?: string;
|
|
495
|
+
}
|
|
496
|
+
/** 可在挂载后更新的展示字段;initiallyVisible 只在挂载时读取,不在此列。 */
|
|
497
|
+
type PanelUpdateOptions = Partial<Pick<PanelOptions, 'contactName' | 'supplementaryInfo'>>;
|
|
498
|
+
/** mountPanel 返回的面板控制句柄。 */
|
|
499
|
+
interface PanelHandle {
|
|
500
|
+
/** 展开面板并聚焦;卸载后无操作。 */
|
|
501
|
+
open(): void;
|
|
502
|
+
/** 收起面板并把焦点还给打开前的宿主元素;不结束通话。卸载后无操作。 */
|
|
503
|
+
close(): void;
|
|
504
|
+
/**
|
|
505
|
+
* 展开面板并请求拨打,等同 Core quickDial,失败提示显示在面板内。
|
|
506
|
+
* @param number 拨打号码
|
|
507
|
+
* @param options quickDial 选项
|
|
508
|
+
* @returns Core 的拨打结果;命令错误已在面板呈现时为 undefined
|
|
509
|
+
* @throws CallCenterError DESTROYED:面板已卸载
|
|
510
|
+
*/
|
|
511
|
+
quickDial(number: string, options?: QuickDialOptions): Promise<QuickDialOutcome | undefined>;
|
|
512
|
+
/**
|
|
513
|
+
* 更新联系人等展示字段;传 undefined 清除宿主值,回落为通话快照中的展示信息。
|
|
514
|
+
* @param options 要更新的字段,未出现的字段保持不变
|
|
515
|
+
*/
|
|
516
|
+
update(options: PanelUpdateOptions): void;
|
|
517
|
+
/** 卸载面板并移除其 DOM;不销毁 Core。重复调用无操作。 */
|
|
518
|
+
unmount(): void;
|
|
519
|
+
}
|
|
520
|
+
/** 运行时全局 API,即 window.ImkAgentSdk。 */
|
|
521
|
+
interface ImkAgentSdkRuntime {
|
|
522
|
+
/** 运行时完整版本号,与 CDN 路径及服务端版本指针一致,如 1.2.3。 */
|
|
523
|
+
readonly version: string;
|
|
524
|
+
/**
|
|
525
|
+
* 创建 Core 实例;创建本身不发请求。
|
|
526
|
+
* @param options 实例选项
|
|
527
|
+
* @returns 宿主唯一的 CallCenter 实例,由宿主负责 destroy
|
|
528
|
+
*/
|
|
529
|
+
createCallCenter(options: CallCenterOptions): CallCenter;
|
|
530
|
+
/**
|
|
531
|
+
* 在目标元素内以 Shadow DOM 挂载通话面板;不需要界面的宿主可不调用。
|
|
532
|
+
* @param target CSS 选择器或元素
|
|
533
|
+
* @param options 面板选项,core 为宿主已创建的实例
|
|
534
|
+
* @returns 面板控制句柄;卸载面板不销毁 Core
|
|
535
|
+
* @throws CallCenterError INVALID_ARGUMENT:目标不存在
|
|
536
|
+
*/
|
|
537
|
+
mountPanel(target: string | HTMLElement, options: PanelOptions): PanelHandle;
|
|
538
|
+
}
|
|
539
|
+
declare global {
|
|
540
|
+
interface Window {
|
|
541
|
+
/** 运行时脚本加载完成后挂载的全局入口。 */
|
|
542
|
+
ImkAgentSdk?: ImkAgentSdkRuntime;
|
|
543
|
+
}
|
|
544
|
+
}
|
|
545
|
+
|
|
546
|
+
/**
|
|
547
|
+
* 按服务端下发的 SdkDelivery 注入运行时脚本,等待加载完成后返回 window.ImkAgentSdk。
|
|
548
|
+
*
|
|
549
|
+
* 客户通过本包锁定大版本;大版本内的小版本由服务端版本指针决定。
|
|
550
|
+
* 同一页面只加载一次运行时,已运行的代码不会被替换,新版本在刷新页面后生效。
|
|
551
|
+
*/
|
|
552
|
+
|
|
553
|
+
/** 加载失败的稳定错误码。 */
|
|
554
|
+
type AgentSdkLoadErrorCode =
|
|
555
|
+
/** sdk 参数缺失或字段不是非空字符串。 */
|
|
556
|
+
'INVALID_ARGUMENT'
|
|
557
|
+
/** 下发版本或页面已加载的运行时与本加载器大版本不一致,需升级加载器包。 */
|
|
558
|
+
| 'MAJOR_VERSION_MISMATCH'
|
|
559
|
+
/** 脚本未能加载或执行:网络、CDN 签名过期、CORS、integrity 校验失败等,浏览器不区分具体原因。 */
|
|
560
|
+
| 'LOAD_FAILED';
|
|
561
|
+
/** 加载器 reject 的错误;message 不含下发地址与签名。 */
|
|
562
|
+
declare class AgentSdkLoadError extends Error {
|
|
563
|
+
/** 稳定错误码,宿主据此分支处理。 */
|
|
564
|
+
readonly code: AgentSdkLoadErrorCode;
|
|
565
|
+
/**
|
|
566
|
+
* @param code 稳定错误码
|
|
567
|
+
* @param message 已脱敏的说明
|
|
568
|
+
*/
|
|
569
|
+
constructor(code: AgentSdkLoadErrorCode, message: string);
|
|
570
|
+
}
|
|
571
|
+
/**
|
|
572
|
+
* 加载服务端下发的 SDK 运行时。
|
|
573
|
+
*
|
|
574
|
+
* 同一页面重复调用返回同一个运行时;页面已通过原生脚本加载时直接采用。
|
|
575
|
+
* 已加载版本与本次 sdk.version 不同时不替换,console 提示刷新页面后生效。
|
|
576
|
+
* @param sdk Ticket 响应中的 data.sdk,原样传入
|
|
577
|
+
* @returns window.ImkAgentSdk
|
|
578
|
+
* @throws AgentSdkLoadError INVALID_ARGUMENT / MAJOR_VERSION_MISMATCH / LOAD_FAILED
|
|
579
|
+
*/
|
|
580
|
+
declare function loadAgentSdk(sdk: SdkDelivery): Promise<ImkAgentSdkRuntime>;
|
|
581
|
+
|
|
582
|
+
export { AgentSdkLoadError, loadAgentSdk };
|
|
583
|
+
export type { AgentCategory, AgentResource, AgentSdkLoadErrorCode, AgentsApi, AudioDeviceInfo, AuthState, CallApi, CallCenter, CallCenterErrorInfo, CallCenterEvent, CallCenterEventMap, CallCenterEventType, CallCenterOptions, CallCenterState, CallDisplay, CallEndReason, CallSnapshot, CallStatus, ClientIdentity, CommandOutcome, ConnectionState, CreateAgentInput, DestroyOptions, DeviceInfo, DevicesApi, DevicesState, DiagnosticEntry, DialOptions, ErrorCode, ErrorKind, ImkAgentSdkRuntime, InitializeResult, LocalHoldState, LogoutResult, LogoutSettlement, NotificationEvent, NotificationEventData, NotificationEventType, PanelHandle, PanelOptions, PanelUpdateOptions, QuickDialBlockedReason, QuickDialOptions, QuickDialOutcome, RegistrationApi, RegistrationState, SdkDelivery, UnauthenticatedReason, Unsubscribe, UpdateAgentInput, WorkStatus, WorkStatusReason, WorkStatusValue };
|