# @fmode/tikhub-server 使用指南

本模块封装了 TikHub API 的调用，支持在 Node.js/Express 服务端直接集成 TikTok 数据采集能力。

## 1. 安装

确保已安装依赖：

```bash
npm install axios express
# 或者
bun install axios express
```

## 2. 快速开始

### 方式一：作为 Express 路由挂载 (推荐)

最简单的使用方式是将模块提供的路由直接挂载到您的 Express 应用中。

```typescript
import express from 'express';
import { createTikHubRouter } from '../modules/fmode-tikhub-server/src/mod';

const app = express();

// 挂载路由到 /api/tikhub 路径下
// 默认使用内置的 API Key 和 Base URL
app.use('/api/tikhub', createTikHubRouter());

// 如果需要自定义配置 (例如更换 API Key)
/*
app.use('/api/tikhub', createTikHubRouter({
  apiKey: 'YOUR_CUSTOM_API_KEY',
  serverURL: 'https://api.tikhub.io/api/v1' // 可选
}));
*/

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});
```

#### API 端点说明

挂载后，您可以通过以下端点访问：

| 功能 | HTTP 方法 | 路径 | 参数 (Query) | 示例 |
| :--- | :--- | :--- | :--- | :--- |
| **搜索用户** | GET | `/search` | `keyword` (必填), `cursor` | `/api/tikhub/search?keyword=cat` |
| **用户详情** | GET | `/users/:uniqueId` | 无 | `/api/tikhub/users/tiktok` |
| **用户作品** | GET | `/users/:secUid/posts` | `count`, `cursor` | `/api/tikhub/users/MS4wLjAB.../posts` |
| **视频评论** | GET | `/posts/:videoId/comments` | `count`, `cursor` | `/api/tikhub/posts/728.../comments` |

---

### 方式二：在代码中直接调用 (Service 模式)

如果您需要在自己的业务逻辑中调用 TikHub API（而不是直接暴露 HTTP 接口），可以使用 `TikHubClient` 和 `TikHubUsersApi` 类。

```typescript
import { TikHubClient, TikHubUsersApi } from '../modules/fmode-tikhub-server/src/mod';

async function main() {
  // 1. 初始化客户端
  const client = new TikHubClient({
    // apiKey: '...' // 可选
  });

  // 2. 创建 API 实例
  const usersApi = new TikHubUsersApi(client);

  try {
    // 示例：搜索用户
    const searchResult = await usersApi.searchUsers({
      keyword: 'elon musk',
      cursor: 0
    });
    console.log('搜索结果:', searchResult);

    // 示例：获取用户详情
    const profile = await usersApi.getUserProfile({
      uniqueId: 'elonmusk' // TikTok handle
    });
    console.log('用户详情:', profile);

  } catch (error) {
    console.error('API 调用失败:', error);
  }
}

main();
```

## 3. 类型定义

模块导出了完整的 TypeScript 类型定义，方便开发使用。

```typescript
import { 
  SearchUsersParams, 
  GetUserProfileParams, 
  TikHubResponse 
} from '../modules/fmode-tikhub-server/src/types';
```

## 4. 配置说明

`TikHubConfig` 接口支持以下选项：

- `apiKey`: (可选) TikHub API Key。如果不传，将使用模块内置的默认 Key。
- `serverURL`: (可选) TikHub API 基础地址。默认为 `https://api.tikhub.io/api/v1`。