catalog/repos/adrianmg--league-sdk.md

# 英雄联盟API开发工具包

`TypeScript` `SDK` `英雄联盟` `Riot API` `npm`

<p align="center">
  <img src="https://raw.githubusercontent.com/adrianmg/league-sdk/main/logo.png" alt="League SDK" width="600">
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/league-sdk"><img src="https://img.shields.io/npm/v/league-sdk.svg" alt="npm 版本"></a>
  <img src="https://img.shields.io/npm/dw/league-sdk.svg" alt="npm 下载量">
  <img src="https://img.shields.io/badge/coverage-92%25-brightgreen" alt="覆盖率">
</p>

# league-sdk

一个完整类型化的 TypeScript SDK，用于访问 Riot 英雄联盟 API。

## 为什么选择这个 SDK？

直接使用原始 Riot API 需要调用多个端点、处理复杂路由并手动转换数据。本 SDK 将一切化繁为简：

**原始 API（多次调用，手动处理）：**
```typescript
// 1. 通过 Riot ID 获取账户（区域端点）
const account = await fetch(`https://asia.api.riotgames.com/riot/account/v1/accounts/by-riot-id/Hide%20on%20bush/KR1?api_key=${key}`);
const { puuid } = await account.json();

// 2. 获取召唤师数据（平台端点）
const summoner = await fetch(`https://kr.api.riotgames.com/lol/summoner/v4/summoners/by-puuid/${puuid}?api_key=${key}`);
const { id: summonerId } = await summoner.json();

// 3. 获取段位数据（平台端点，不同 ID）
const leagues = await fetch(`https://kr.api.riotgames.com/lol/league/v4/entries/by-puuid/${puuid}?api_key=${key}`);
const ranked = await leagues.json();
const soloQ = ranked.find(q => q.queueType === 'RANKED_SOLO_5x5');

// 4. 手动计算胜率
const winRate = soloQ.wins / (soloQ.wins + soloQ.losses);
```

**使用 league-sdk：**
```typescript
const player = await client.players.getByRiotId('Hide on bush', 'KR1');
const soloQ = await player.getSoloQueueStats();
console.log(`${soloQ.tier} ${soloQ.division} - ${(soloQ.winRate * 100).toFixed(1)}% 胜率`);
```

## 快速上手

### 安装

```bash
npm install league-sdk
# 或
bun add league-sdk
```

### API 密钥

前往 [developer.riotgames.com](https://developer.riotgames.com/) 获取密钥。开发者密钥有效期 24 小时（每秒 20 次，每 2 分钟 100 次）。如需永久密钥，请注册产品。

### 快速示例

```typescript
import { LolClient } from 'league-sdk';

const client = new LolClient({
  apiKey: process.env.RIOT_API_KEY!,
  platform: 'kr'
});

// 获取玩家及其段位数据
const player = await client.players.getByRiotId('Hide on bush', 'KR1');
const soloQ = await player.getSoloQueueStats();

// 获取近期对局
const matches = await client.matches.getForPlayer(player.puuid, { count: 5 });
for (const match of matches) {
  const p = match.getParticipant(player.puuid)!;
  console.log(`${p.championName}: ${p.kills}/${p.deaths}/${p.assists}`);
}
```

### 开发环境

```bash
bun install && bun test
```

```bash
# 适用于 AI Agent 的技能
npx skills add https://github.com/adrianmg/league-sdk --skill league-sdk
```

## 功能特性

| 服务 | 说明 | 示例 |
|------|------|------|
| **Players（玩家）** | 通过 Riot ID 或 PUUID 查询 | `client.players.getByRiotId('Name', 'Tag')` |
| **Matches（对局）** | 对局历史与详情 | `client.matches.getForPlayer(puuid)` |
| **Mastery（熟练度）** | 英雄熟练度数据 | `client.mastery.getForPlayer(puuid)` |
| **Live Game（实时对局）** | 当前对局观战信息 | `client.liveGame.getForPlayer(puuid)` |
| **Status（状态）** | 服务器健康状态 | `client.status.get('euw1')` |
| **Challenges（挑战）** | 挑战任务进度 | `client.challenges.getPlayerProfile(puuid)` |
| **Clash（冠军杯）** | 赛事信息 | `client.clash.getPlayer(puuid)` |
| **Data Dragon（静态数据）** | 静态数据（无需密钥） | `client.dataDragon.getChampions()` |

## 实体对象

```typescript
// 玩家
const player = await client.players.getByRiotId('Hide on bush', 'KR1');
player.puuid; player.riotId; player.level;
await player.getSoloQueueStats();

// 对局
const match = await client.matches.getById('EUW1_1234567890');
match.gameMode; match.gameDurationFormatted; match.winner;
const p = match.getParticipant(puuid)!;
p.kills; p.deaths; p.assists; p.kda; p.csPerMinute;
```

## 常量与工具函数

```typescript
import { PLATFORMS, QUEUES, isRankedQueue, formatRank, compareRanks } from 'league-sdk';

PLATFORMS.EUW1           // 'euw1'
isRankedQueue(420)       // true（单双排）
formatRank('DIAMOND', 'II')  // "钻石 II"
compareRanks('DIAMOND', 'II', 'PLATINUM', 'I')  // 1（钻石 > 铂金）
```

## 错误处理

类型化错误：`NotFoundError`、`RateLimitError`（含 `retryAfter`）、`AuthenticationError`。

## 资源下载

```bash
npx league-sdk-assets --output ./assets --all
```

也可通过 `league-sdk/scripts` 使用程序化 API。

## 请求限速

内置限速器（每秒 20 次，每 2 分钟 100 次）。可通过 `rateLimiter` 选项配置，或使用 `client.getRateLimitStatus()` 查看当前状态。

## 示例服务器

```bash
RIOT_API_KEY=your-key bun run example/server.ts
```

## 支持的平台

| 平台 | 区域 | 位置 |
|------|------|------|
| `na1` | americas | 北美 |
| `br1` | americas | 巴西 |
| `la1` | americas | 拉丁美洲北部 |
| `la2` | americas | 拉丁美洲南部 |
| `euw1` | europe | 欧洲西部 |
| `eun1` | europe | 欧洲北欧及东部 |
| `tr1` | europe | 土耳其 |
| `ru` | europe | 俄罗斯 |
| `kr` | asia | 韩国 |
| `jp1` | asia | 日本 |
| `oc1` | sea | 大洋洲 |
| `ph2` | sea | 菲律宾 |
| `sg2` | sea | 新加坡 |
| `th2` | sea | 泰国 |
| `tw2` | sea | 台湾 |
| `vn2` | sea | 越南 |

## 许可证

MIT

## 致谢

本项目在 GitHub Copilot 和 Claude 等 AI 编程工具的协助下开发完成。