npm package: @qzsy/mineru-sdk
Description: Mineru SDK for browser usage
Author: huanghuabin
Latest version: 0.1.0

# Mineru SDK

Mineru SDK是一个用于浏览器环境的JavaScript/TypeScript工具包，用于与Mineru文档解析API进行交互。通过该SDK，你可以轻松地将Mineru的强大文档解析能力集成到你的Web应用中。

## 功能特性

- 创建单个文件解析任务
- 获取任务状态和结果
- 批量获取文件上传链接
- 上传本地文件并解析
- 批量创建URL文件解析任务
- 批量获取任务状态
- 任务状态轮询
- 错误处理和日志记录

## 安装

使用npm/yarn/pnpm安装:

```bash
# 使用npm
npm install @qzsy/mineru-sdk

# 使用yarn
yarn add @qzsy/mineru-sdk

# 使用pnpm
pnpm add @qzsy/mineru-sdk
```

## 快速开始

### 基本用法

```typescript
import { MineruSDK } from '@qzsy/mineru-sdk';

// 创建SDK实例
const sdk = new MineruSDK('YOUR_API_TOKEN');

// 创建单个URL文件解析任务
async function createTask() {
  try {
    const response = await sdk.createTask({
      url: 'https://example.com/document.pdf',
      is_ocr: true,
      enable_formula: true
    });
    
    console.log('任务ID:', response.data.task_id);
    
    // 获取任务状态
    const status = await sdk.getTaskStatus(response.data.task_id);
    console.log('任务状态:', status.data.state);
  } catch (error) {
    console.error('Error:', error);
  }
}

createTask();
```

### 上传本地文件并解析

```typescript
import { MineruSDK } from '@qzsy/mineru-sdk';

const sdk = new MineruSDK('YOUR_API_TOKEN');

async function uploadAndAnalyze(file) {
  try {
    // 获取上传链接
    const urlResponse = await sdk.getBatchFileUrls({
      files: [{ name: file.name, is_ocr: true }]
    });
    
    const batchId = urlResponse.data.batch_id;
    const uploadUrl = urlResponse.data.file_urls[0];
    
    // 上传文件
    await sdk.uploadFile(uploadUrl, file);
    
    // 轮询任务直到完成
    const result = await sdk.pollBatchTaskUntilComplete(batchId);
    console.log('解析结果:', result.data);
  } catch (error) {
    console.error('Error:', error);
  }
}

// 在浏览器中使用
document.getElementById('fileInput').addEventListener('change', (e) => {
  const file = e.target.files[0];
  uploadAndAnalyze(file);
});
```

### 轮询任务状态直到完成

```typescript
import { MineruSDK } from '@qzsy/mineru-sdk';

const sdk = new MineruSDK('YOUR_API_TOKEN');

async function createAndWaitForCompletion() {
  try {
    // 创建任务
    const response = await sdk.createTask({
      url: 'https://example.com/document.pdf',
      is_ocr: true
    });
    
    const taskId = response.data.task_id;
    
    // 轮询任务直到完成，默认每3秒检查一次，最多尝试100次
    const finalStatus = await sdk.pollTaskUntilComplete(taskId);
    
    if (finalStatus.data.state === 'done') {
      console.log('任务完成! 下载链接:', finalStatus.data.full_zip_url);
    } else {
      console.error('任务失败:', finalStatus.data.err_msg);
    }
  } catch (error) {
    console.error('Error:', error);
  }
}

createAndWaitForCompletion();
```

## API参考

### MineruSDK类

#### 构造函数

```typescript
constructor(token: string, config?: AxiosRequestConfig)
```

- `token`: Mineru API令牌
- `config`: 可选的Axios配置对象

#### 方法

##### 创建单个任务

```typescript
async createTask(params: CreateTaskParams): Promise<MineruResponse<CreateTaskResponse>>
```

##### 获取任务状态

```typescript
async getTaskStatus(taskId: string): Promise<MineruResponse<TaskStatusResponse>>
```

##### 批量获取文件上传链接

```typescript
async getBatchFileUrls(params: BatchFileUploadParams): Promise<MineruResponse<BatchFileUploadResponse>>
```

##### 上传文件到预签名URL

```typescript
async uploadFile(url: string, file: Blob): Promise<boolean>
```

##### 批量创建URL任务

```typescript
async createBatchUrlTasks(params: BatchURLTaskParams): Promise<MineruResponse<BatchURLTaskResponse>>
```

##### 获取批量任务状态

```typescript
async getBatchTaskStatus(batchId: string): Promise<MineruResponse<BatchTaskStatusResponse>>
```

##### 检查任务是否完成

```typescript
async isTaskCompleted(taskId: string): Promise<boolean>
```

##### 轮询任务直到完成

```typescript
async pollTaskUntilComplete(
  taskId: string,
  intervalMs: number = 3000,
  maxAttempts: number = 100
): Promise<MineruResponse<TaskStatusResponse>>
```

##### 轮询批量任务直到完成

```typescript
async pollBatchTaskUntilComplete(
  batchId: string,
  intervalMs: number = 3000,
  maxAttempts: number = 100
): Promise<MineruResponse<BatchTaskStatusResponse>>
```

### 工具类

SDK还提供了一个`MineruUtils`工具类，包含多个辅助函数：

- `parsePageRanges`: 解析页面范围字符串
- `getMimeTypeFromFilename`: 从文件名获取MIME类型
- `generateUniqueId`: 生成唯一ID
- `checkFileSize`: 检查文件大小是否超出限制
- `formatProgressPercentage`: 格式化进度百分比
- `estimateRemainingTime`: 估计剩余时间

## 示例

查看`examples`目录中的完整示例：
- `basic-usage.ts`: 基本SDK使用示例
- `browser-example.html`: 浏览器集成完整示例

## 注意事项

- 单个文件大小不能超过200MB
- 文件页数不能超过600页
- 由于网络限制，某些国外URL（如github、aws等）可能会请求超时

## 错误码

SDK内置了常见错误码的处理，主要错误码包括：

| 错误码 | 说明 | 解决建议 |
|---------|---------|---------|
| A0202 | Token错误 | 检查Token是否正确，或者更换新Token |
| A0211 | Token过期 | 更换新Token |
| -10001 | 服务异常 | 请稍后再试 |
| -10002 | 请求参数错误 | 检查请求参数格式 |
| -60001 | 生成上传URL失败 | 请稍后再试 |
| -60004 | 空文件 | 请上传有效文件 |
| -60005 | 文件大小超出限制 | 检查文件大小，最大支持200MB |
| -60006 | 文件页数超过限制 | 请拆分文件后重试 |

更多错误码请参考官方文档。

## 许可证

MIT