# xn-fe-tools

基于 Vue 3 Composition API 的工具库，提供 HTTP 请求工具 `toAwaitFetch` 和 Sentry 统一初始化工具集等能力。

## ✨ 特性

- 双模式：链式调用与解构 `[data, error, success]`
- 完整错误处理：HTTP / 业务 / 网络 / 超时，支持钩子与抑制抛错
- 重试与超时：内置重试策略、可自定义 shouldRetry，支持超时与取消
- 多种请求/响应类型：JSON、FormData、Blob
- 全局配置：baseURL、headers、validateStatus、validateResponse、transformResponse 等
- TypeScript 全量类型定义，零外部依赖（基于原生 Fetch）
- **Sentry 统一初始化**：支持 Vue 3 / Vue 2 / React / 纯浏览器，零安装成本，主包体积不受影响

## 📦 安装

```bash
# npm
npm install xn-fe-tools
# pnpm
pnpm add xn-fe-tools
# yarn
yarn add xn-fe-tools
```

## 🚀 快速使用

### 解构模式

```ts
import { sendGet, sendPost } from 'xn-fe-tools'

const [list, listError, ok] = await sendGet('/api/users')
const [created] = await sendPost('/api/users', { name: 'John' })
```

### 链式模式

```ts
import { toAwaitFetch } from 'xn-fe-tools'

toAwaitFetch
  .sendGet('/api/users')
  .catchHttp((err) => console.error('HTTP 错误', err))
  .catchBusiness((err) => console.error('业务错误', err))
  .catchNetwork((err) => console.error('网络/超时错误', err))
```

### 创建实例并统一配置（推荐）

```ts
import { createInstance } from 'xn-fe-tools'

const http = createInstance({
  baseURL: '',
  timeout: 5000,
  headers: ({ url, method }) => ({
    Authorization: `Bearer ${localStorage.getItem('token') || ''}`,
    'X-Request-Path': url,
    'X-Request-Method': method || 'GET',
  }),
  validateResponse: (res) => res.code === 200,
  transformResponse: (res) => res.data,
  retry: {
    enabled: true,
    maxRetryCount: 3,
    delay: 1000,
    shouldRetry: async (attempt, fetchError) => {
      if (fetchError.type === 'business' && fetchError.response?.code === 401) {
        return false
      }
      return true
    },
  },
  mode: 'cors',
  credentials: 'include',
})

const [data] = await http.sendGet('/api/users', undefined, { timeout: 2000 })
```

### 取消请求

```ts
import { sendGet } from 'xn-fe-tools'

const request = sendGet('/api/users', undefined, { timeout: 8000 })
request.cancel()
const [, error, success] = await request // 被取消时 error.type === 'timeout' 或 'network'
```


## 🛡️ Sentry 集成

通过独立子路径引入，主包体积不受影响，Sentry SDK 已内置打包无需额外安装：

```ts
// Vue 3（支持 Vue Router 路由追踪）
import { toVue3SentrySetup } from 'xn-fe-tools/sentry/vue3'

toVue3SentrySetup({
  dsn: 'https://xxx@sentry.io/xxx',
  app,    // Vue 3 应用实例，必填
  router, // Vue Router，可选
})

// Vue 2 / React / 纯浏览器
import { toVue2SentrySetup } from 'xn-fe-tools/sentry/vue2'
import { toReactSentrySetup } from 'xn-fe-tools/sentry/react'
import { toSentrySetup } from 'xn-fe-tools/sentry/browser'
```

返回值提供运行时控制能力：

```ts
const { isInitialized, captureException, captureMessage, setUser } = toVue3SentrySetup({ ... })
```

简化配置参数（无需了解 Sentry 集成 API）：

```ts
toVue3SentrySetup({
  dsn: '...',
  app,
  enableTracing: true,   // 控制 browserTracingIntegration，默认 true
  enableReplay: false,   // 控制 replayIntegration，默认 true
  breadcrumbs: { console: false }, // 控制面包屑行为
})
```

Vite Source Map 上传配置辅助：

```ts
// vite.config.ts
import { sentryVitePlugin } from '@sentry/vite-plugin' // 需单独安装为 devDependency
import { getSentryViteConfig } from 'xn-fe-tools/sentry/browser'

export default defineConfig({
  plugins: [sentryVitePlugin(getSentryViteConfig({
    org: 'my-org',
    project: 'my-project',
    authToken: process.env.SENTRY_AUTH_TOKEN,
  }))],
  build: { sourcemap: true },
})
```

## 📦 版本信息

```ts
import { VERSION, getVersion } from 'xn-fe-tools'

console.log(VERSION)
console.log(getVersion())
```

## 🤖 MCP 支持（AI 助手集成）

xn-fe-tools 内置了 [MCP（Model Context Protocol）](https://modelcontextprotocol.io/) 服务端，安装后 AI 助手可以自动获取所有 Hook 的 API 信息、使用文档、最佳实践和代码模板，帮助你正确使用最新功能。

### 配置

在项目中创建 MCP 配置文件：

> **注意：** `xn-fe-tools-mcp` 是 `xn-fe-tools` 包内注册的 bin 命令，不是独立的 npm 包。必须通过 `-p` 参数指定包名。

**Kiro** — `.kiro/settings/mcp.json`：

```json
{
  "mcpServers": {
    "xn-fe-tools": {
      "command": "npx",
      "args": ["-p", "xn-fe-tools", "xn-fe-tools-mcp"]
    }
  }
}
```

**Cursor** — `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "xn-fe-tools": {
      "command": "npx",
      "args": ["-p", "xn-fe-tools", "xn-fe-tools-mcp"]
    }
  }
}
```

**Claude Code** — `.mcp.json`：

```json
{
  "mcpServers": {
    "xn-fe-tools": {
      "command": "npx",
      "args": ["-p", "xn-fe-tools", "xn-fe-tools-mcp"]
    }
  }
}
```

如果项目已安装 xn-fe-tools，也可以直接指向本地文件：

```json
{
  "mcpServers": {
    "xn-fe-tools": {
      "command": "node",
      "args": ["node_modules/xn-fe-tools/dist/mcp/server.mjs"]
    }
  }
}
```

配置完成后，AI 助手即可通过以下工具获取信息：

| 工具 | 说明 |
|------|------|
| `list_hooks` | 列出所有可用 Hook |
| `get_hook_detail` | 查询 Hook 的 API 类型定义 |
| `get_hook_doc` | 获取 Hook 使用文档 |
| `get_hook_usage_rule` | 获取 Hook 使用规则和最佳实践 |
| `get_hook_template` | 获取代码模板（支持 Element Plus / Ant Design Vue） |

## 📄 License

MIT