@ztlink-imk/ztlinkcloud-agent-sdk 0.0.0-stage → 1.0.1
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 +101 -0
- package/dist/index.d.cts +583 -0
- package/dist/index.d.ts +583 -0
- package/dist/index.js +78 -0
- package/package.json +29 -3
package/README.md
CHANGED
|
@@ -1,3 +1,94 @@
|
|
|
1
|
-
#
|
|
1
|
+
# 坐席 SDK 加载器
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
```bash
|
|
4
|
+
npm i @ztlink-imk/ztlinkcloud-agent-sdk
|
|
5
|
+
```
|
|
6
|
+
|
|
7
|
+
SDK 实现不在本包内:客户服务端签发 Ticket 时,响应 `data.sdk` 同时给出运行时地址(带 CDN 签名)、版本与 integrity。浏览器加载该脚本后得到 `window.ImkAgentSdk`。本包负责注入脚本并提供公共类型,没有运行时依赖。
|
|
8
|
+
|
|
9
|
+
客户通过本包锁定**大版本**;大版本内的小版本由服务端决定,发版或回退后客户刷新页面即生效。
|
|
10
|
+
|
|
11
|
+
## 接入前提
|
|
12
|
+
|
|
13
|
+
- CSP `script-src` 加入 CDN 域名 `imk-cdn.ztlink.com`。
|
|
14
|
+
- `sdk.url` 带有有效期有限的签名,每次打开页面使用本次 Ticket 响应中的值,不要缓存或写死。
|
|
15
|
+
- Ticket 只在内存中传给 `initialize`,不要写进 URL、DOM 属性或存储。
|
|
16
|
+
|
|
17
|
+
## 方式一:npm 加载器(Vite、Webpack 等构建工具)
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import { loadAgentSdk, AgentSdkLoadError } from '@ztlink-imk/ztlinkcloud-agent-sdk';
|
|
21
|
+
|
|
22
|
+
// 宿主后端调用 POST /openapi/v1/agent-login-tickets 后,把 ticket 与 sdk 一起交给前端
|
|
23
|
+
const { ticket, sdk } = await fetchTicketFromHostBackend();
|
|
24
|
+
|
|
25
|
+
try {
|
|
26
|
+
const runtime = await loadAgentSdk(sdk); // sdk 为 { version, url, integrity },原样传入
|
|
27
|
+
const core = runtime.createCallCenter({ apiBaseUrl, wsUrl });
|
|
28
|
+
const panel = runtime.mountPanel('#imk-panel', { core }); // 不需要界面时可不调用
|
|
29
|
+
await core.initialize(ticket);
|
|
30
|
+
} catch (error) {
|
|
31
|
+
if (error instanceof AgentSdkLoadError) {
|
|
32
|
+
// error.code: INVALID_ARGUMENT | MAJOR_VERSION_MISMATCH | LOAD_FAILED
|
|
33
|
+
}
|
|
34
|
+
throw error;
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
- 产物为 ESM + CJS,附带自包含的 `.d.ts`;JavaScript 项目不需要类型也可直接使用。
|
|
39
|
+
- 同一页面重复调用返回同一个运行时。页面已加载的版本与本次 `sdk.version` 不同时不替换已运行的代码,控制台提示刷新页面后生效;需要自行提示时比较 `runtime.version !== sdk.version`。
|
|
40
|
+
|
|
41
|
+
| 错误码 | 含义 | 处理 |
|
|
42
|
+
|---|---|---|
|
|
43
|
+
| `INVALID_ARGUMENT` | `sdk` 缺少非空的 `version`/`url`/`integrity` | 检查宿主后端是否原样转发 `data.sdk` |
|
|
44
|
+
| `MAJOR_VERSION_MISMATCH` | 下发版本或页面已加载的运行时大版本与加载器不一致 | 升级加载器包 |
|
|
45
|
+
| `LOAD_FAILED` | 网络、签名过期、CORS、integrity 校验失败等,浏览器不区分原因 | 重新签发 Ticket 获取新地址后重试 |
|
|
46
|
+
|
|
47
|
+
## 方式二:原生脚本(JSP、jQuery、纯 HTML 等无构建工具的页面)
|
|
48
|
+
|
|
49
|
+
简化写法,只演示注入脚本与大版本校验;不含加载器的参数校验、同页单飞、失败后移除脚本以便重试等处理,有构建工具时优先使用方式一:
|
|
50
|
+
|
|
51
|
+
```html
|
|
52
|
+
<div id="imk-panel"></div>
|
|
53
|
+
<script>
|
|
54
|
+
function loadAgentSdk(sdk) {
|
|
55
|
+
// 先校验大版本,再复用页面上已加载的运行时(新小版本刷新页面后生效)
|
|
56
|
+
if (String(sdk.version).split('.')[0] !== '1')
|
|
57
|
+
return Promise.reject(new Error('MAJOR_VERSION_MISMATCH'));
|
|
58
|
+
if (window.ImkAgentSdk) return Promise.resolve(window.ImkAgentSdk);
|
|
59
|
+
return new Promise(function (resolve, reject) {
|
|
60
|
+
var script = document.createElement('script');
|
|
61
|
+
script.src = sdk.url;
|
|
62
|
+
script.integrity = sdk.integrity;
|
|
63
|
+
script.crossOrigin = 'anonymous'; // 必须设置,浏览器才会校验 integrity
|
|
64
|
+
script.onload = function () {
|
|
65
|
+
window.ImkAgentSdk ? resolve(window.ImkAgentSdk) : reject(new Error('LOAD_FAILED'));
|
|
66
|
+
};
|
|
67
|
+
script.onerror = function () {
|
|
68
|
+
script.remove();
|
|
69
|
+
reject(new Error('LOAD_FAILED'));
|
|
70
|
+
};
|
|
71
|
+
document.head.appendChild(script);
|
|
72
|
+
});
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
// data 为宿主后端转发的 Ticket 响应 data:{ ticket, sdk, ... }
|
|
76
|
+
fetchTicketFromHostBackend()
|
|
77
|
+
.then(function (data) {
|
|
78
|
+
return loadAgentSdk(data.sdk).then(function (runtime) {
|
|
79
|
+
var core = runtime.createCallCenter({ apiBaseUrl: '...', wsUrl: '...' });
|
|
80
|
+
runtime.mountPanel('#imk-panel', { core: core });
|
|
81
|
+
return core.initialize(data.ticket);
|
|
82
|
+
});
|
|
83
|
+
})
|
|
84
|
+
.catch(function (error) {
|
|
85
|
+
console.error('坐席 SDK 加载失败', error);
|
|
86
|
+
});
|
|
87
|
+
</script>
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## 面板与无界面接入
|
|
91
|
+
|
|
92
|
+
- `mountPanel(target, options)` 在目标元素内以 Shadow DOM 挂载通话面板,与宿主框架(Vue 2/3、React、原生)无关;返回 `{ open, close, quickDial, update, unmount }`。`unmount` 不销毁 Core。
|
|
93
|
+
- 面板不提供插槽。需要自定义界面的宿主不调用 `mountPanel`,直接用 `core.getState()` 与 `core.subscribe()` / `core.on()` 维护自己的界面状态。
|
|
94
|
+
- 不支持 `adoptedStyleSheets` 的浏览器(如 Safari 16.4 以前)面板样式回退为 `<style>`,严格 CSP 下需允许内联样式。
|
package/dist/index.cjs
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __defProp = Object.defineProperty;
|
|
3
|
+
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
4
|
+
var __getOwnPropNames = Object.getOwnPropertyNames;
|
|
5
|
+
var __hasOwnProp = Object.prototype.hasOwnProperty;
|
|
6
|
+
var __export = (target, all) => {
|
|
7
|
+
for (var name in all)
|
|
8
|
+
__defProp(target, name, { get: all[name], enumerable: true });
|
|
9
|
+
};
|
|
10
|
+
var __copyProps = (to, from, except, desc) => {
|
|
11
|
+
if (from && typeof from === "object" || typeof from === "function") {
|
|
12
|
+
for (let key of __getOwnPropNames(from))
|
|
13
|
+
if (!__hasOwnProp.call(to, key) && key !== except)
|
|
14
|
+
__defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
|
|
15
|
+
}
|
|
16
|
+
return to;
|
|
17
|
+
};
|
|
18
|
+
var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
|
|
19
|
+
|
|
20
|
+
// src/index.ts
|
|
21
|
+
var index_exports = {};
|
|
22
|
+
__export(index_exports, {
|
|
23
|
+
AgentSdkLoadError: () => AgentSdkLoadError,
|
|
24
|
+
loadAgentSdk: () => loadAgentSdk
|
|
25
|
+
});
|
|
26
|
+
module.exports = __toCommonJS(index_exports);
|
|
27
|
+
|
|
28
|
+
// src/load-agent-sdk.ts
|
|
29
|
+
var SUPPORTED_MAJOR = 1;
|
|
30
|
+
var AgentSdkLoadError = class extends Error {
|
|
31
|
+
/** 稳定错误码,宿主据此分支处理。 */
|
|
32
|
+
code;
|
|
33
|
+
/**
|
|
34
|
+
* @param code 稳定错误码
|
|
35
|
+
* @param message 已脱敏的说明
|
|
36
|
+
*/
|
|
37
|
+
constructor(code, message) {
|
|
38
|
+
super(message);
|
|
39
|
+
this.name = "AgentSdkLoadError";
|
|
40
|
+
this.code = code;
|
|
41
|
+
}
|
|
42
|
+
};
|
|
43
|
+
var pending = null;
|
|
44
|
+
function majorOf(version) {
|
|
45
|
+
const match = /^(\d+)\.\d+\.\d+/.exec(version);
|
|
46
|
+
return match ? Number(match[1]) : null;
|
|
47
|
+
}
|
|
48
|
+
var INTEGRITY_PATTERN = /^sha384-[A-Za-z0-9+/]{64}$/;
|
|
49
|
+
function isDelivery(sdk) {
|
|
50
|
+
if (typeof sdk !== "object" || sdk === null) return false;
|
|
51
|
+
const { version, url, integrity } = sdk;
|
|
52
|
+
return [version, url].every((field) => typeof field === "string" && field !== "") && typeof integrity === "string" && INTEGRITY_PATTERN.test(integrity);
|
|
53
|
+
}
|
|
54
|
+
function adopt(runtime, sdk) {
|
|
55
|
+
if (majorOf(runtime.version) !== SUPPORTED_MAJOR)
|
|
56
|
+
throw new AgentSdkLoadError("MAJOR_VERSION_MISMATCH", "\u9875\u9762\u5DF2\u52A0\u8F7D\u7684\u8FD0\u884C\u65F6\u5927\u7248\u672C\u4E0E\u52A0\u8F7D\u5668\u4E0D\u4E00\u81F4");
|
|
57
|
+
if (runtime.version !== sdk.version)
|
|
58
|
+
console.warn(
|
|
59
|
+
`[imk-agent-sdk] \u9875\u9762\u5DF2\u8FD0\u884C ${runtime.version}\uFF0C\u670D\u52A1\u7AEF\u5F53\u524D\u7248\u672C ${sdk.version} \u5C06\u5728\u5237\u65B0\u9875\u9762\u540E\u751F\u6548`
|
|
60
|
+
);
|
|
61
|
+
return runtime;
|
|
62
|
+
}
|
|
63
|
+
function inject(sdk) {
|
|
64
|
+
return new Promise((resolve, reject) => {
|
|
65
|
+
const script = document.createElement("script");
|
|
66
|
+
script.src = sdk.url;
|
|
67
|
+
script.integrity = sdk.integrity;
|
|
68
|
+
script.crossOrigin = "anonymous";
|
|
69
|
+
script.async = true;
|
|
70
|
+
script.onload = () => {
|
|
71
|
+
const runtime = window.ImkAgentSdk;
|
|
72
|
+
if (runtime) {
|
|
73
|
+
resolve(runtime);
|
|
74
|
+
return;
|
|
75
|
+
}
|
|
76
|
+
script.remove();
|
|
77
|
+
reject(new AgentSdkLoadError("LOAD_FAILED", "\u8FD0\u884C\u65F6\u811A\u672C\u5DF2\u6267\u884C\u4F46\u672A\u6302\u8F7D ImkAgentSdk"));
|
|
78
|
+
};
|
|
79
|
+
script.onerror = () => {
|
|
80
|
+
script.remove();
|
|
81
|
+
reject(new AgentSdkLoadError("LOAD_FAILED", "\u8FD0\u884C\u65F6\u811A\u672C\u52A0\u8F7D\u5931\u8D25"));
|
|
82
|
+
};
|
|
83
|
+
document.head.append(script);
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
async function loadAgentSdk(sdk) {
|
|
87
|
+
if (!isDelivery(sdk))
|
|
88
|
+
throw new AgentSdkLoadError(
|
|
89
|
+
"INVALID_ARGUMENT",
|
|
90
|
+
"sdk \u9700\u5305\u542B\u975E\u7A7A\u7684 version\u3001url \u53CA sha384 \u683C\u5F0F\u7684 integrity"
|
|
91
|
+
);
|
|
92
|
+
if (majorOf(sdk.version) !== SUPPORTED_MAJOR)
|
|
93
|
+
throw new AgentSdkLoadError("MAJOR_VERSION_MISMATCH", "\u670D\u52A1\u7AEF\u4E0B\u53D1\u7684\u8FD0\u884C\u65F6\u5927\u7248\u672C\u4E0E\u52A0\u8F7D\u5668\u4E0D\u4E00\u81F4");
|
|
94
|
+
const loaded = window.ImkAgentSdk;
|
|
95
|
+
if (loaded) return adopt(loaded, sdk);
|
|
96
|
+
pending ??= inject(sdk).catch((error) => {
|
|
97
|
+
pending = null;
|
|
98
|
+
throw error;
|
|
99
|
+
});
|
|
100
|
+
return adopt(await pending, sdk);
|
|
101
|
+
}
|