customer-chat-sdk 1.0.0

package/README.md

@@ -0,0 +1,267 @@
+# Customer SDK
+
+一个轻量级的客服系统SDK，帮助开发者快速集成客服聊天功能到现有的Web应用中。
+
+## 🚀 特性
+
+- **轻量级集成**: 一行代码快速接入
+- **悬浮图标**: 页面右下角悬浮聊天图标
+- **响应式设计**: PC弹窗模式 / 移动端全屏模式
+- **设备指纹**: 自动获取设备唯一标识
+- **iframe隔离**: 完全隔离的聊天界面，避免样式冲突
+- **通知系统**: 红点徽章、数字提醒功能
+- **跨平台支持**: 支持UMD、ESM、CJS多种模块格式
+
+## 📦 安装
+
+### CDN 引入
+
+```html
+<script src="https://cdn.example.com/customer-sdk.min.js"></script>
+<script>
+  CustomerSDK.init({
+    agent: 'your_agent_id',
+    userId: 'user_123',
+    token: 'jwt_token',
+    chatUrl: 'https://chat.example.com'
+  });
+</script>
+```
+
+### NPM 安装
+
+```bash
+npm install customer-chat-sdk```
+
+```javascript
+import CustomerSDK from 'customer-chat-sdk';
+
+CustomerSDK.init({
+  agent: 'your_agent_id',
+  userId: 'user_123', 
+  token: 'jwt_token',
+  chatUrl: 'https://chat.example.com'
+});
+```
+
+## 🔧 快速开始
+
+### 基础用法
+
+```javascript
+// 初始化SDK
+await CustomerSDK.init({
+  agent: 'agent_123',
+  userId: 'user_456', 
+  token: 'jwt_token_here',
+  chatUrl: 'https://chat.example.com',
+  debug: true
+});
+
+// 关闭悬浮图标
+CustomerSDK.hideIcon();
+
+// 打开悬浮图标
+CustomerSDK.showIcon();
+
+// 打开聊天窗口
+CustomerSDK.openChat();
+
+// 检查聊天窗口是否打开
+const isOpen = CustomerSDK.isChatOpen();
+
+// 显示通知
+CustomerSDK.showNotification(5); // 数字徽章
+CustomerSDK.showNotification('NEW'); // 文本徽章
+CustomerSDK.clearNotification(); // 清除通知
+```
+
+### 高级配置
+
+```javascript
+// 完整的配置选项
+await CustomerSDK.init({
+  agent: 'your_agent_id',
+  userId: 'your_user_id',
+  token: 'your_jwt_token',
+  chatUrl: 'https://chat.example.com',
+  apiBaseUrl: 'https://api.example.com',
+  debug: true
+}, {
+  // iframe选项（可选）
+  width: 400,
+  height: 600,
+  mode: 'auto', // 'auto' | 'fullscreen' | 'popup'
+  draggable: false,
+  resizable: false,
+  allowClose: true
+});
+```
+
+## 📖 API 文档
+
+### 初始化方法
+
+#### `CustomerSDK.init(config, options?)`
+
+初始化Customer SDK，自动获取设备指纹ID并创建隐藏iframe。
+
+**参数：**
+
+- `config` (SDKConfig): SDK配置选项
+- `options` (ChatWindowOptions?, 可选): iframe窗口选项
+
+**SDKConfig:**
+```typescript
+interface SDKConfig {
+  agent: string;           // 代理商ID
+  userId: string;          // 用户ID  
+  token: string;           // 认证令牌
+  chatUrl: string;         // 聊天页面URL (必需)
+  apiBaseUrl?: string;     // API基础地址
+  debug?: boolean;         // 调试模式
+}
+```
+
+### 核心方法
+
+#### `CustomerSDK.openChat()` / `CustomerSDK.closeChat()`
+
+打开或关闭iframe聊天窗口。
+
+#### `CustomerSDK.showIcon()` / `CustomerSDK.hideIcon()`
+
+显示或隐藏悬浮图标。
+
+#### `CustomerSDK.isChatOpen()`
+
+检查聊天窗口是否打开。
+
+**返回：** boolean
+
+#### `CustomerSDK.sendToIframe(data)`
+
+向iframe发送数据消息。
+
+**参数：**
+- `data` (any): 要发送的数据
+
+#### `CustomerSDK.showNotification(badgeCount, options?)`
+
+显示通知徽章。
+
+**参数：**
+- `badgeCount` (number | string): 徽章内容（数字或文本）
+- `options` (object?, 可选): { pulse?: boolean, autoHide?: number }
+
+#### `CustomerSDK.clearNotification()`
+
+清除通知徽章。
+
+## 🌐 URL 参数
+
+SDK会向iframe URL自动添加以下参数：
+
+- `agent`: 代理商ID
+- `userId`: 用户ID
+- `token`: 认证令牌
+- `deviceId`: 设备指纹ID（通过FingerprintJS自动获取）
+- `debug`: 调试模式
+
+**最终URL示例：**
+```
+https://chat.example.com?agent=demo_app&userId=1703123456&token=test_token_1703123456789&deviceId=abc123xyz&debug=true
+```
+
+## 🔧 响应式设计
+
+SDK自动检测设备类型并应用相应样式：
+
+**PC模式：**
+- 悬浮图标：右下角圆形图标
+- 聊天窗口：居中弹窗，带关闭按钮
+
+**移动端模式：**  
+- 悬浮图标：保持不变
+- 聊天窗口：全屏显示，右上角关闭按钮
+
+## 🛠️ 开发
+
+### 环境要求
+
+- Node.js >= 18
+- pnpm >= 8 (推荐) 或 npm >= 9
+
+### 安装依赖
+
+```bash
+# 使用pnpm (推荐)
+pnpm install
+
+# 或者使用传统npm
+npm install
+```
+
+### 开发命令
+
+```bash
+# 启动开发服务器
+pnpm dev
+
+# 启动Demo页面
+pnpm demo
+
+# 构建生产版本
+pnpm build
+
+# 代码检查
+pnpm lint
+
+# 格式化代码
+pnpm format
+
+# 检查依赖更新
+pnpm package-check
+```
+
+### 项目结构
+
+```
+src/
+├── core/           # 核心SDK功能
+│   ├── CustomerSDK.ts      # SDK主类
+│   ├── IconManager.ts      # 悬浮图标管理
+│   └── IframeManager.ts    # iframe管理
+├── types/              # TypeScript类型定义
+└── index.ts            # 主入口文件
+```
+
+## 🔗 iframe 通信
+
+SDK通过postMessage与iframe进行通信：
+
+```javascript
+// 向iframe发送数据
+CustomerSDK.sendToIframe({
+  type: 'userInfo',
+  data: {
+    userId: 'user_123',
+    profile: { name: 'John', avatar: '...' }
+  }
+});
+
+// iframe接收示例
+window.addEventListener('message', (event) => {
+  if (event.data.type === 'userInfo') {
+    console.log('收到用户信息:', event.data.data);
+  }
+});
+```
+
+## 📄 许可证
+
+MIT License
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！

package/dist/core/CustomerSDK.d.ts

@@ -0,0 +1,66 @@
+import { SDKConfig } from '../types';
+export declare class CustomerSDK {
+    private config;
+    private iconManager;
+    private iframeManager;
+    private isInitialized;
+    constructor();
+    /**
+     * 初始化SDK
+     */
+    init(config: SDKConfig): Promise<void>;
+    /**
+     * 隐藏图标
+     */
+    hideIcon(): void;
+    /**
+     * 显示图标
+     */
+    showIcon(): void;
+    /**
+     * 打开聊天窗口
+     */
+    openChat(): void;
+    /**
+     * 关闭聊天窗口
+     */
+    closeChat(): void;
+    /**
+     * 检查聊天窗口是否打开
+     */
+    isChatOpen(): boolean;
+    /**
+     * 发送消息给iframe
+     */
+    sendToIframe(data: any): void;
+    /**
+     * 获取连接状态
+     */
+    getConnectionStatus(): {
+        connected: boolean;
+    };
+    /**
+     * 显示消息通知
+     */
+    showNotification(badgeCount?: number | string, options?: {
+        pulse?: boolean;
+        autoHide?: number;
+    }): void;
+    /**
+     * 清除消息通知
+     */
+    clearNotification(): void;
+    /**
+     * 销毁 SDK
+     */
+    destroy(): void;
+    /**
+     * 获取设备指纹ID
+     */
+    private getDeviceId;
+    /**
+     * 构建iframe URL（带用户参数和设备ID）
+     */
+    private buildIframeUrl;
+}
+//# sourceMappingURL=CustomerSDK.d.ts.map

package/dist/core/CustomerSDK.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CustomerSDK.d.ts","sourceRoot":"","sources":["../../src/core/CustomerSDK.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAKpC,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,WAAW,CAA2B;IAC9C,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,aAAa,CAAQ;;IAI7B;;OAEG;IACG,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAwC5C;;OAEG;IACH,QAAQ,IAAI,IAAI;IAIhB;;OAEG;IACH,QAAQ,IAAI,IAAI;IAIhB;;OAEG;IACH,QAAQ,IAAI,IAAI;IAIhB;;OAEG;IACH,SAAS,IAAI,IAAI;IAIjB;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI;IAM7B;;OAEG;IACH,mBAAmB,IAAI;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE;IAI7C;;OAEG;IACH,gBAAgB,CAAC,UAAU,GAAE,MAAM,GAAG,MAAU,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,IAAI;IAoB7G;;OAEG;IACH,iBAAiB,IAAI,IAAI;IAIzB;;OAEG;IACH,OAAO,IAAI,IAAI;IAUf;;OAEG;YACW,WAAW;IAkBzB;;OAEG;IACH,OAAO,CAAC,cAAc;CAqBvB"}

package/dist/core/IconManager.d.ts

@@ -0,0 +1,55 @@
+interface NotificationOptions {
+    showBadge?: boolean;
+    badgeCount?: number;
+    badgeText?: string;
+    pulse?: boolean;
+}
+export declare class IconManager {
+    private iconElement;
+    private badgeElement;
+    private onClickCallback;
+    private notificationCallback;
+    constructor();
+    /**
+     * 显示悬浮图标
+     */
+    show(): Promise<void>;
+    /**
+     * 隐藏悬浮图标
+     */
+    hide(): void;
+    /**
+     *  setPosition（暂时保留接口兼容性）
+     */
+    setPosition(position: any): void;
+    /**
+     * setStyle（暂时保留接口兼容性）
+     */
+    setStyle(style: any): void;
+    /**
+     * 设置点击回调
+     */
+    onClick(callback: () => void): void;
+    /**
+     * 设置消息通知回调
+     */
+    onNotification(callback: (data: any) => void): void;
+    /**
+     * 显示消息订阅（红点、数字等）
+     */
+    showNotification(options: NotificationOptions): void;
+    /**
+     * 清除消息订阅
+     */
+    clearNotification(): void;
+    /**
+     * 处理点击事件
+     */
+    private handleClick;
+    /**
+     * 创建消息徽章（简化版）
+     */
+    private createBadge;
+}
+export {};
+//# sourceMappingURL=IconManager.d.ts.map

package/dist/core/IconManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IconManager.d.ts","sourceRoot":"","sources":["../../src/core/IconManager.ts"],"names":[],"mappings":"AAEA,UAAU,mBAAmB;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,WAAW,CAA2B;IAC9C,OAAO,CAAC,YAAY,CAA2B;IAC/C,OAAO,CAAC,eAAe,CAA4B;IACnD,OAAO,CAAC,oBAAoB,CAAqC;;IAIjE;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA4C3B;;OAEG;IACH,IAAI,IAAI,IAAI;IASZ;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,GAAG,GAAG,IAAI;IAIhC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI;IAI1B;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAInC;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,GAAG,IAAI;IAInD;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI;IA0BpD;;OAEG;IACH,iBAAiB,IAAI,IAAI;IAQzB;;OAEG;IACH,OAAO,CAAC,WAAW;IAMnB;;OAEG;IACH,OAAO,CAAC,WAAW;CAgDpB"}

package/dist/core/IframeManager.d.ts

@@ -0,0 +1,93 @@
+interface IframeOptions {
+    src?: string;
+    mode?: 'auto' | 'fullscreen' | 'popup';
+    width?: number;
+    height?: number;
+    draggable?: boolean;
+    resizable?: boolean;
+    allowClose?: boolean;
+}
+export declare class IframeManager {
+    private config;
+    private iframeElement;
+    private overlayElement;
+    private containerElement;
+    private isOpen;
+    private isCreated;
+    constructor(config?: IframeOptions);
+    /**
+     * 初始化iframe（隐藏状态）
+     * 预创建iframe并连接到SSE，但不显示
+     */
+    init(): Promise<void>;
+    /**
+     * 显示iframe聊天窗口
+     */
+    show(): void;
+    /**
+     * 打开iframe聊天窗口（保持兼容性）
+     */
+    open(): void;
+    /**
+     * 隐藏iframe聊天窗口（类似v-show）
+     */
+    hide(): void;
+    /**
+     * 关闭iframe聊天窗口（完全销毁，保持兼容性）
+     */
+    close(): void;
+    /**
+     * 完全销毁iframe（需要时才调用）
+     */
+    destroy(): void;
+    /**
+     * 检查是否已打开
+     */
+    isIframeOpen(): boolean;
+    /**
+     * 向iframe发送消息
+     */
+    sendToIframe(data: any): void;
+    /**
+     * 创建遮罩层
+     */
+    private createOverlay;
+    /**
+     * 创建iframe（默认隐藏状态，用于SSE连接）
+     */
+    private createIframe;
+    /**
+     * 向iframe注入移动端优化样式（隐藏滚动条）
+     */
+    private injectMobileStyles;
+    /**
+     * 控制页面滚动（移动端全屏模式使用）
+     */
+    private preventBodyScroll;
+    /**
+     * 添加关闭按钮（自适应设备）
+     */
+    private addCloseButton;
+    /**
+     * 检测设备类型
+     */
+    private isMobileDevice;
+    /**
+     * 获取当前显示模式
+     */
+    private getActualMode;
+    /**
+     * 设置消息监听
+     */
+    private setupMessageListener;
+    /**
+     * 处理来自iframe的消息
+     */
+    private handleIframeMessage;
+    /**
+     * 调整iframe大小
+     */
+    private resizeIframe;
+}
+export {};
+//# sourceMappingURL=IframeManager.d.ts.map

package/dist/core/IframeManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IframeManager.d.ts","sourceRoot":"","sources":["../../src/core/IframeManager.ts"],"names":[],"mappings":"AAEA,UAAU,aAAa;IACrB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,OAAO,CAAA;IACtC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,aAAa,CAAiC;IACtD,OAAO,CAAC,cAAc,CAA2B;IACjD,OAAO,CAAC,gBAAgB,CAA2B;IACnD,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,SAAS,CAAQ;gBAEb,MAAM,GAAE,aAAkB;IAatC;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAc3B;;OAEG;IACH,IAAI,IAAI,IAAI;IA6DZ;;OAEG;IACH,IAAI,IAAI,IAAI;IAIZ;;OAEG;IACH,IAAI,IAAI,IAAI;IA8BZ;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,OAAO,IAAI,IAAI;IAaf;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI;IAM7B;;OAEG;IACH,OAAO,CAAC,aAAa;IA8BrB;;OAEG;IACH,OAAO,CAAC,YAAY;IAuFpB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA0D1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAmCzB;;OAEG;IACH,OAAO,CAAC,cAAc;IAkFtB;;OAEG;IACH,OAAO,CAAC,cAAc;IAKtB;;OAEG;IACH,OAAO,CAAC,aAAa;IAOrB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAS5B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAsB3B;;OAEG;IACH,OAAO,CAAC,YAAY;CAMrB"}