# LOFTER 任务系统 SDK

一个用于处理 LOFTER 任务系统的前端 NPM 包，提供完整的 TypeScript 类型定义和数据预处理功能。

## 特性

- 🚀 **零依赖** - 不绑定特定的 HTTP 客户端
- 🔒 **完整的 TypeScript 支持** - 提供完整的类型定义和智能提示
- 📊 **数据预处理** - 自动计算任务状态、进度百分比等衍生数据
- 🌐 **真实 API 集成** - 直接调用 LOFTER 官方接口
- 🛠 **便捷的工具函数** - 任务过滤、排序、状态检查等工具
- 📦 **多种构建格式** - 支持 CommonJS、ES Modules、UMD

## 安装

```bash
npm install @lofter-mission/core
```

## 快速开始

### 1. 最简单的使用方式（推荐）

```typescript
import { MissionApiService } from '@lofter-mission/core';

// 直接创建实例，SDK会自动使用默认配置
const missionApi = new MissionApiService();

// 获取活动数据
const activityCode = 'confession'; // 活动代码
const processedData = await missionApi.getProcessedActivityData(activityCode);

console.log('活动信息:', {
  isActive: processedData.missionActivity.isActive,
  timeRemaining: processedData.missionActivity.timeRemainingText,
  userPoints: processedData.userInfo.points,
  hasNewMissions: processedData.userInfo.hasClaimableMissions
});

// 获取可领取的任务
const claimableMissions = await missionApi.getClaimableMissions('confession');
console.log(`有 ${claimableMissions.length} 个任务可以领取`);
```

### 2. 自定义配置

```typescript
import { MissionApiService } from '@lofter-mission/core';

// 自定义baseURL或headers
const missionApi = new MissionApiService({
  baseURL: 'https://custom-api.example.com', // 可选：自定义API地址
  headers: {
    'Custom-Header': 'custom-value' // 可选：自定义请求头
  }
});
```

### 3. 使用自定义 HTTP 客户端（高级用法）

如果需要使用axios或其他HTTP库：

```typescript
import axios from 'axios';
import { MissionApiService } from '@lofter-mission/core';

const missionApi = new MissionApiService({
  httpClient: axios, // 自定义HTTP客户端
  headers: {
    'User-Agent': 'MyApp/1.0.0'
  }
});
```

### 4. 在不同环境中使用

#### 浏览器环境
```typescript
// 直接使用，SDK会自动使用浏览器的fetch
const missionApi = new MissionApiService();
```

#### Node.js环境
```bash
# 需要fetch polyfill
npm install node-fetch
```

```typescript
// 方式1：使用node-fetch polyfill
import fetch from 'node-fetch';
global.fetch = fetch;

const missionApi = new MissionApiService();

// 方式2：使用axios
import axios from 'axios';
const missionApi = new MissionApiService({ httpClient: axios });
```

#### uni-app环境
```typescript
import { MissionApiService, HttpClient } from '@lofter-mission/core';

// 自定义 HTTP 客户端（比如 uni-app 的 uni.request）
const uniHttpClient: HttpClient = {
  async get<T>(url: string, config?: any): Promise<{ data: T }> {
    let targetUrl = url;
    const queryParams = new URLSearchParams(config?.params || {});
    if (queryParams.toString()) {
      targetUrl = `${url}?${queryParams.toString()}`;
    }
    
    return new Promise((resolve, reject) => {
      uni.request({
        url: targetUrl,
        method: 'GET',
        header: config?.headers,
        success: (res) => resolve({ data: res.data as T }),
        fail: reject
      });
    });
  },

  async post<T>(url: string, data?: any, config?: any): Promise<{ data: T }> {
    return new Promise((resolve, reject) => {
      uni.request({
        url,
        method: 'POST',
        data,
        header: {
          'Content-Type': 'application/json',
          ...config?.headers
        },
        success: (res) => resolve({ data: res.data as T }),
        fail: reject
      });
    });
  }
};

const missionApi = new MissionApiService({
  httpClient: uniHttpClient
});
```

## API 参考

### MissionApiService

主要的 API 服务类，提供与 LOFTER 任务系统交互的方法。

#### 构造函数

```typescript
new MissionApiService(config: MissionApiConfig)
```

**参数：**
- `config.httpClient`: HTTP 客户端实例
- `config.baseURL?`: 基础 URL（默认为 LOFTER 官方接口）
- `config.headers?`: 默认请求头

#### 主要方法

##### `getProcessedActivityData(activityCode: string)`

获取预处理后的活动数据，包含计算后的状态和进度信息。

**参数：**
- `activityCode`: 活动代码（如 'confession'）

**返回：** `Promise<ProcessedActivityData>`

##### `getActivityData(activityCode: string)`

获取原始的活动数据，直接调用 LOFTER 接口。

**参数：**
- `activityCode`: 活动代码

**返回：** `Promise<ActivityDataResponseData>`

##### `getClaimableMissions(activityCode: string)`

获取所有可领取的任务。

**返回：** `Promise<ProcessedMissionInfo[]>`

##### `getCompletableMissions(activityCode: string)`

获取所有可完成的任务。

**返回：** `Promise<ProcessedMissionInfo[]>`

##### `hasNewMissions(activityCode: string)`

检查是否有新的可领取任务。

**返回：** `Promise<boolean>`

### MissionProcessor

数据处理器，提供静态方法处理任务数据。

#### 主要方法

##### `processActivityData(rawData: ActivityDataResponseData)`

处理原始活动数据，添加计算字段。

**返回：** `ProcessedActivityData`

##### `getMissionsByType(data: ProcessedActivityData, missionType: MissionType)`

按任务类型过滤任务。

##### `getAllClaimableMissions(data: ProcessedActivityData)`

获取所有可领取的任务。

##### `getAllCompletableMissions(data: ProcessedActivityData)`

获取所有可完成的任务。

## 类型定义

### 主要接口

```typescript
// 任务类型
type MissionType = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22;

// 任务状态
type MissionStatus = -1 | 0 | 1 | 2; // -1未完成, 0可领取, 1已领取, 2抢完了

// 活动状态
type ActivityStatus = -1 | 0 | 1; // -1未开始, 0进行中, 1已结束

// 任务信息
interface MissionInfo {
  code: string;
  title: string;
  subTitle: string;
  missionType: MissionType;
  missionStatus: MissionStatus;
  currentProgress: number;
  totalProgress: number;
  awardName: string;
  awardNum: number;
  // ... 更多字段
}

// 处理后的任务信息（包含计算字段）
interface ProcessedMissionInfo extends MissionInfo {
  isClaimable: boolean;
  isCompleted: boolean;
  isCompletable: boolean;
  progressPercentage: number;
  progressText: string;
  highlightedTitle: string;
  timeRemainingText?: string;
}
```

## 真实接口地址

SDK 默认调用以下 LOFTER 官方接口：

- **活动概览**：`https://www.lofter.com/spread/mission/overview.json?activityCode={activityCode}`
  
## 常见活动代码

- `confession` - 表白活动
- `summer2024` - 夏日活动
- `daily` - 每日任务

## 支持的任务类型

1. **签到任务** (type: 1)
2. **分享任务** (type: 2) 
3. **浏览任务** (type: 3)
4. **抽卡任务** (type: 4)
5. **累计抽卡** (type: 5)
6. **聊聊评论** (type: 6)
7. **邀请任务** (type: 7)
8. **系统自动完成** (type: 8)
9. **卡牌升级** (type: 9)
10. **发文任务** (type: 10)
11. **创作新设定作品** (type: 12)
12. **投稿作品单篇热度** (type: 13)
13. **标签文章推荐** (type: 14)
14. **其他任务类型** (type: 15-22)

## 开发

```bash
# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 测试
npm test

# 代码检查
npm run lint
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 更新日志

### v1.0.0
- 初始版本发布
- 支持 LOFTER 真实接口调用
- 完整的 TypeScript 类型定义
- 数据预处理功能
- 零依赖设计

### v1.1.0
- 🎉 **简化使用方式** - httpClient现在是可选参数，SDK自动提供默认实现
- 🔧 **默认配置** - 自动设置合理的默认请求头和baseURL
- 🛠 **更好的错误处理** - 改进HTTP请求错误处理
- 📱 **多环境支持** - 更好地支持浏览器、Node.js和uni-app环境