league-sdk

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

<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 version"></a>
  <img src="https://img.shields.io/npm/dw/league-sdk.svg" alt="npm downloads">
  <img src="https://img.shields.io/badge/coverage-92%25-brightgreen" alt="coverage">
</p>

# league-sdk

A fully typed TypeScript SDK for the Riot League of Legends API.

## Why This SDK?

Working with the raw Riot API requires multiple endpoints, complex routing, and manual data transformation. This SDK simplifies everything:

**Raw API (multiple calls, manual work):**
```typescript
// 1. Get account by Riot ID (regional endpoint)
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. Get summoner data (platform endpoint)
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. Get ranked stats (platform endpoint, different 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. Calculate win rate manually
const winRate = soloQ.wins / (soloQ.wins + soloQ.losses);
```

**With 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)}% WR`);
```

## Getting Started

### Installation

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

### API Key

Get your key at [developer.riotgames.com](https://developer.riotgames.com/). Dev keys last 24h (20/s, 100/2min). Register a product for permanent keys.

### Quick Start

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

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

// Get player and their ranked stats
const player = await client.players.getByRiotId('Hide on bush', 'KR1');
const soloQ = await player.getSoloQueueStats();

// Get recent matches
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}`);
}
```

### Development

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

```bash
# Skill for AI Agents
npx skills add https://github.com/adrianmg/league-sdk --skill league-sdk
```

## Features

| Service | Description | Example |
|---------|-------------|---------|
| **Players** | Lookup by Riot ID or PUUID | `client.players.getByRiotId('Name', 'Tag')` |
| **Matches** | Match history and details | `client.matches.getForPlayer(puuid)` |
| **Mastery** | Champion mastery stats | `client.mastery.getForPlayer(puuid)` |
| **Live Game** | Current game spectator | `client.liveGame.getForPlayer(puuid)` |
| **Status** | Server health | `client.status.get('euw1')` |
| **Challenges** | Challenge progress | `client.challenges.getPlayerProfile(puuid)` |
| **Clash** | Tournament info | `client.clash.getPlayer(puuid)` |
| **Data Dragon** | Static data (no key needed) | `client.dataDragon.getChampions()` |

## Entities

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

// Match
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;
```

## Constants & Helpers

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

PLATFORMS.EUW1           // 'euw1'
isRankedQueue(420)       // true (Solo/Duo)
formatRank('DIAMOND', 'II')  // "Diamond II"
compareRanks('DIAMOND', 'II', 'PLATINUM', 'I')  // 1 (Diamond > Plat)
```

## Error Handling

Typed errors: `NotFoundError`, `RateLimitError` (has `retryAfter`), `AuthenticationError`.

## Asset Downloads

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

Programmatic API also available via `league-sdk/scripts`.

## Rate Limiting

Built-in rate limiter (20/s, 100/2min). Configure via `rateLimiter` option or check status with `client.getRateLimitStatus()`.

## Example Server

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

## Platforms

| Platform | Region | Location |
|----------|--------|----------|
| `na1` | americas | North America |
| `br1` | americas | Brazil |
| `la1` | americas | Latin America North |
| `la2` | americas | Latin America South |
| `euw1` | europe | EU West |
| `eun1` | europe | EU Nordic & East |
| `tr1` | europe | Turkey |
| `ru` | europe | Russia |
| `kr` | asia | Korea |
| `jp1` | asia | Japan |
| `oc1` | sea | Oceania |
| `ph2` | sea | Philippines |
| `sg2` | sea | Singapore |
| `th2` | sea | Thailand |
| `tw2` | sea | Taiwan |
| `vn2` | sea | Vietnam |

## License

MIT

## Acknowledgments

This project was developed with assistance from AI coding tools including GitHub Copilot and Claude.

npm downloads

league-sdk

A fully typed TypeScript SDK for the Riot League of Legends API.

Why This SDK?

Working with the raw Riot API requires multiple endpoints, complex routing, and manual data transformation. This SDK simplifies everything:

Raw API (multiple calls, manual work):

// 1. Get account by Riot ID (regional endpoint)
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. Get summoner data (platform endpoint)
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. Get ranked stats (platform endpoint, different 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. Calculate win rate manually
const winRate = soloQ.wins / (soloQ.wins + soloQ.losses);

With league-sdk:

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)}% WR`);

Getting Started

Installation

npm install league-sdk
# or
bun add league-sdk

API Key

Get your key at developer.riotgames.com. Dev keys last 24h (20/s, 100/2min). Register a product for permanent keys.

Quick Start

import { LolClient } from 'league-sdk';

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

// Get player and their ranked stats
const player = await client.players.getByRiotId('Hide on bush', 'KR1');
const soloQ = await player.getSoloQueueStats();

// Get recent matches
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}`);
}

Development

bun install && bun test

# Skill for AI Agents
npx skills add https://github.com/adrianmg/league-sdk --skill league-sdk

Features

Service	Description	Example
Players	Lookup by Riot ID or PUUID	`client.players.getByRiotId('Name', 'Tag')`
Matches	Match history and details	`client.matches.getForPlayer(puuid)`
Mastery	Champion mastery stats	`client.mastery.getForPlayer(puuid)`
Live Game	Current game spectator	`client.liveGame.getForPlayer(puuid)`
Status	Server health	`client.status.get('euw1')`
Challenges	Challenge progress	`client.challenges.getPlayerProfile(puuid)`
Clash	Tournament info	`client.clash.getPlayer(puuid)`
Data Dragon	Static data (no key needed)	`client.dataDragon.getChampions()`

Entities

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

// Match
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;

Constants & Helpers

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

PLATFORMS.EUW1           // 'euw1'
isRankedQueue(420)       // true (Solo/Duo)
formatRank('DIAMOND', 'II')  // "Diamond II"
compareRanks('DIAMOND', 'II', 'PLATINUM', 'I')  // 1 (Diamond > Plat)

Error Handling

Typed errors: NotFoundError, RateLimitError (has retryAfter), AuthenticationError.

Asset Downloads

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

Programmatic API also available via league-sdk/scripts.

Rate Limiting

Built-in rate limiter (20/s, 100/2min). Configure via rateLimiter option or check status with client.getRateLimitStatus().

Example Server

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

Platforms

Platform	Region	Location
`na1`	americas	North America
`br1`	americas	Brazil
`la1`	americas	Latin America North
`la2`	americas	Latin America South
`euw1`	europe	EU West
`eun1`	europe	EU Nordic & East
`tr1`	europe	Turkey
`ru`	europe	Russia
`kr`	asia	Korea
`jp1`	asia	Japan
`oc1`	sea	Oceania
`ph2`	sea	Philippines
`sg2`	sea	Singapore
`th2`	sea	Thailand
`tw2`	sea	Taiwan
`vn2`	sea	Vietnam

License

MIT

Acknowledgments

This project was developed with assistance from AI coding tools including GitHub Copilot and Claude.