npm package: @mu-cabin/ai-beeper
Description: AI utility functions for frontend applications
Latest version: 1.0.10

# AI Beeper

一个 AI-Beeper bot 对话框工具，提供可拖拽和自定义的 AI 聊天界面。

## Installation 安装

```bash
npm install @mu-cabin/ai-beeper
# or
yarn add @mu-cabin/ai-beeper
# or
pnpm add @mu-cabin/ai-beeper
```

## Usage 使用方法

### Token Generation 令牌生成

获取 token 请访问: http://10.73.202.13:8080/share/token

### Basic AIChat Implementation 基础 AIChat 实现

```typescript
import { AIChat } from '@mu-cabin/ai-beeper';

// Create a new AIChat instance
// 创建一个新的 AIChat 实例
const aiChat = new AIChat({
  token: 'auth-token', // 认证令牌，从 http://10.73.202.13:8080/share/token 获取
  baseUrl: 'https://your-api-url.com', // 可选，AI-beeper URL，一般不用填写
  draggable: true, // 可选，是否可拖拽，默认为 true
  trigger: 'click', // 可选，触发方式：'click' 或 'hover'，默认为 'click'
  width: 600, // 可选，弹出框宽度
  height: 600, // 可选，弹出框高度
  lazyLoad: true, // 可选，是否懒加载
  position: { // 可选，初始位置
    x: 'calc(100% - 100px)', // 距离右边 100px
    y: 'calc(100% - 100px)', // 距离底部 100px
  },
});

// Clean up when done
// 使用完毕后清理
aiChat.destroy();
```

### React Integration Example React 集成示例

```typescript
import React, { useRef, useEffect } from 'react';
import { AIBeeper } from '@mu-cabin/ai-beeper';

const AIChatComponent = () => {
  const instanceRef = useRef<AIBeeper | null>(null);

  useEffect(() => {
    instanceRef.current = new AIBeeper({
      token: 'auth-token', // 认证令牌，从 http://10.73.202.13:8080/share/token 获取
      draggable: true,
      trigger: 'click',
      position: {
        x: 'calc(100% - 100px)',
        y: 'calc(100% - 100px)',
      },
    });

    return () => {
      instanceRef.current?.destroy();
    };
  }, []);

  return null; // The chat interface will be rendered as a floating element
  // 聊天界面将作为浮动元素渲染
};
```

## Configuration Options 配置选项

The `AIChat` class accepts the following configuration options:
`AIChat` 类接受以下配置选项：

| Option 选项 | Type 类型 | Default 默认值 | Description 描述 |
|------------|-----------|---------------|-----------------|
| token | string | required 必填 | Authentication token 认证令牌，从 http://10.73.202.13:8080/share/token 获取 |
| baseUrl | string | 'http://10.73.202.13:8080' | Base URL for the chat API 聊天 API 的基础 URL |
| width | number | 600 | Width of the chat popover 聊天弹出框宽度 |
| height | number | 600 | Height of the chat popover 聊天弹出框高度 |
| draggable | boolean | true | Whether the chat button is draggable 聊天按钮是否可拖拽 |
| trigger | 'hover' \| 'click' | 'click' | How to trigger the chat popover 如何触发聊天弹出框 |
| popoverStyle | CSSStyleDeclaration | - | Custom styles for the popover 弹出框的自定义样式 |
| buttonStyle | CSSStyleDeclaration | - | Custom styles for the chat button 聊天按钮的自定义样式 |
| content | HTMLElement \| string | - | Custom content for the chat button 聊天按钮的自定义内容 |
| lazyLoad | boolean | true | Whether to lazy load the iframe content 是否懒加载 iframe 内容 |
| iconAnimation | boolean | true | Whether to enable the bot icon animation (breathing/bounce effect) 是否启用机器人图标动画（呼吸/弹跳效果） |
| position | { x: string \| number, y: string \| number } | - | Initial position of the chat button. Supports CSS calc() expressions, percentages, viewport units, and pixel values 聊天按钮的初始位置。支持 CSS calc() 表达式、百分比、视口单位和像素值 |

### Position Examples 位置示例

```typescript
// Using calc() expressions
position: {
  x: 'calc(100% - 100px)', // 距离右边 100px
  y: 'calc(100% - 100px)', // 距离底部 100px
}

// Using percentages
position: {
  x: '50%',  // 水平居中
  y: '50%',  // 垂直居中
}

// Using viewport units
position: {
  x: '75vw', // 视口宽度的 75%
  y: '25vh', // 视口高度的 25%
}

// Using pixel values
position: {
  x: '20px', // 距离左边 20px
  y: '20px', // 距离顶部 20px
}
```

## Project Structure 项目结构

```
ai-beeper/
├── src/                    # 源代码目录
│   ├── AIChat.ts          # AIChat 类主实现
│   ├── Popover.ts         # 弹出框组件实现
│   ├── utils.ts           # 工具函数
│   └── index.ts           # 包入口文件
├── preview/               # 预览和示例组件
├── dist/                 # 编译输出目录
├── package.json          # 项目配置文件
├── tsconfig.json         # TypeScript 配置
└── README.md             # 项目说明文档
```

## Development 开发

1. Clone the repository 克隆仓库
2. Install dependencies 安装依赖:
   ```bash
   pnpm install
   ```
3. Build the package 构建包:
   ```bash
   pnpm build
   ```
4. Run tests 运行测试:
   ```bash
   pnpm test
   ```

## License 许可证

MIT