Package Exports

@zqz979/league-api-wrapper
@zqz979/league-api-wrapper/ddragon

Readme

League API Wrapper

NPM Version GitHub Actions Workflow Status GitHub License

Features
Installation
Prerequisites
Quick Start
Modular Imports
API Reference
Examples
Convenience Utilities
Error Handling
Rate Limiting
Environment Variables
TypeScript Support
CI/CD & Publishing
Contributing
License
Disclaimer
Support

A comprehensive TypeScript wrapper for the Riot Games League of Legends API. This library provides type-safe access to all League of Legends API endpoints with a clean, modern interface.

Features

🔒 Type-safe - Full TypeScript support with complete type definitions
🌍 Multi-region support - Works with all Riot Games regions and platforms
🧩 Modular design - Import only the clients you need
📦 Tree-shakable - Optimized bundle size with ES modules
🚀 Modern - Built with modern JavaScript/TypeScript best practices
⚡ Axios-based - Reliable HTTP client with proper error handling

Installation

npm install @zqz979/league-api-wrapper

yarn add @zqz979/league-api-wrapper

pnpm add @zqz979/league-api-wrapper

bun add @zqz979/league-api-wrapper

Prerequisites

You'll need a Riot Games API key to use this library. Get one from the Riot Developer Portal.

Quick Start

Basic Usage

import {RiotClient} from '@zqz979/league-api-wrapper';

const client = new RiotClient({
  apiKey: 'YOUR_RIOT_API_KEY',
});

// Get summoner information
const summoner = await client.summoner.getSummonerByEncryptedPUUID(
  'NA1',
  'puuid',
);
console.log(summoner.name);

// Get match data
const match = await client.match.getMatchByMatchId('AMERICAS', 'match_id');
console.log(match.info.gameDuration);

Modular Imports

You can import individual clients and types directly from the main entry point for optimal tree-shaking:

import {
  SummonerClient,
  MatchClient,
  SummonerDTO,
} from '@zqz979/league-api-wrapper';

const summonerClient = new SummonerClient({apiKey: 'YOUR_API_KEY'});
const matchClient = new MatchClient({apiKey: 'YOUR_API_KEY'});

// Use types for type-safe responses
const summoner: SummonerDTO = await summonerClient.getSummonerByEncryptedPUUID(
  'NA1',
  puuid,
);

Convenience Utilities

This library is designed for flexibility, but you can easily add your own helper functions for common tasks. Example:

Summoner Lookup Utility

async function lookupSummonerByName(
  client: SummonerClient,
  platform: string,
  name: string,
) {
  // You may need to implement Riot ID lookup logic here
  return await client.getSummonerByName(platform, name);
}

Match Summary Utility

function summarizeMatch(match: MatchDto) {
  return {
    gameId: match.metadata.matchId,
    duration: match.info.gameDuration,
    participants: match.info.participants.map(p => ({
      summonerName: p.summonerName,
      champion: p.championName,
      win: p.win,
      kills: p.kills,
      deaths: p.deaths,
      assists: p.assists,
    })),
  };
}

CI/CD & Publishing

This package uses GitHub Actions for automated testing and publishing to npm. On every release, the workflow runs type checks, linting, formatting, and builds before publishing.

See .github/workflows/npm-publish.yml for details.

API Reference

Available Clients

The library provides clients for all League of Legends API endpoints:

AccountClient - Account information and cross-game data
SummonerClient - Summoner profiles and basic information
ChampionClient - Champion rotations and champion data
MatchClient - Match history, match details, and timelines
LeagueClient - Ranked league information
LeagueExpClient - Experimental league endpoints
SpectatorClient - Live game spectator data
ChampionMasteryClient - Champion mastery scores and information
ChallengeClient - Player challenges and achievements
ClashClient - Clash tournament information
StatusClient - Server status and maintenance information

Regions and Platforms

Platforms (for most endpoints)

type Platform =
  | 'BR1' // Brazil
  | 'EUN1' // Europe Nordic & East
  | 'EUW1' // Europe West
  | 'JP1' // Japan
  | 'KR' // Korea
  | 'LA1' // Latin America North
  | 'LA2' // Latin America South
  | 'NA1' // North America
  | 'OC1' // Oceania
  | 'TR1' // Turkey
  | 'RU' // Russia
  | 'PH2' // Philippines
  | 'SG2' // Singapore
  | 'TH2' // Thailand
  | 'TW2' // Taiwan
  | 'VN2'; // Vietnam

Regions (for match and account endpoints)

type Region =
  | 'AMERICAS' // North and South America
  | 'ASIA' // Asia Pacific
  | 'EUROPE' // Europe
  | 'SEA'; // Southeast Asia

Examples

Getting Summoner Information

import {RiotClient} from '@zqz979/league-api-wrapper';

const client = new RiotClient({apiKey: 'YOUR_API_KEY'});

async function getSummonerInfo(puuid: string) {
  try {
    const summoner = await client.summoner.getSummonerByEncryptedPUUID(
      'NA1',
      puuid,
    );

    console.log(`Summoner: ${summoner.name}`);
    console.log(`Level: ${summoner.summonerLevel}`);
    console.log(`Account ID: ${summoner.accountId}`);

    return summoner;
  } catch (error) {
    console.error('Failed to fetch summoner:', error);
    throw error;
  }
}

Getting Match History

async function getRecentMatches(puuid: string) {
  try {
    // Get recent match IDs
    const matchIds = await client.match.getMatchIdsByPuuid(
      'AMERICAS',
      puuid,
      undefined, // startTime
      undefined, // endTime
      undefined, // queue
      undefined, // type
      0, // start
      10, // count - get last 10 matches
    );

    // Get detailed match data
    const matches = await Promise.all(
      matchIds.map(matchId =>
        client.match.getMatchByMatchId('AMERICAS', matchId),
      ),
    );

    return matches;
  } catch (error) {
    console.error('Failed to fetch matches:', error);
    throw error;
  }
}

Getting Live Game Information

async function getLiveGame(summonerId: string) {
  try {
    const liveGame = await client.spectator.getCurrentGameInfoBySummonerId(
      'NA1',
      summonerId,
    );

    console.log(`Game Mode: ${liveGame.gameMode}`);
    console.log(`Game Length: ${liveGame.gameLength}s`);
    console.log(`Participants: ${liveGame.participants.length}`);

    return liveGame;
  } catch (error) {
    if (error.response?.status === 404) {
      console.log('Summoner is not currently in a game');
      return null;
    }
    throw error;
  }
}

Getting Champion Mastery

async function getChampionMastery(summonerId: string) {
  try {
    const masteries =
      await client.championMastery.getChampionMasteryBySummonerId(
        'NA1',
        summonerId,
      );

    // Sort by mastery points
    const sortedMasteries = masteries.sort(
      (a, b) => b.championPoints - a.championPoints,
    );

    console.log('Top 5 Champions:');
    sortedMasteries.slice(0, 5).forEach((mastery, index) => {
      console.log(
        `${index + 1}. Champion ${mastery.championId}: ${mastery.championPoints} points (Level ${mastery.championLevel})`,
      );
    });

    return sortedMasteries;
  } catch (error) {
    console.error('Failed to fetch champion mastery:', error);
    throw error;
  }
}

Error Handling

import {AxiosError} from 'axios';

async function handleApiCall() {
  try {
    const summoner = await client.summoner.getSummonerByEncryptedPUUID(
      'NA1',
      'invalid-puuid',
    );
    return summoner;
  } catch (error) {
    if (error instanceof AxiosError) {
      switch (error.response?.status) {
        case 401:
          console.error('Invalid API key');
          break;
        case 403:
          console.error('Forbidden - check API key permissions');
          break;
        case 404:
          console.error('Summoner not found');
          break;
        case 429:
          console.error('Rate limit exceeded');
          break;
        case 500:
          console.error('Internal server error');
          break;
        default:
          console.error('Unexpected error:', error.message);
      }
    }
    throw error;
  }
}

Rate Limiting

This library does not implement automatic rate limiting. You should implement rate limiting on your end to comply with Riot's API rate limits:

Personal API Key: 100 requests every 2 minutes
Production API Key: Varies based on approval

Consider using libraries like bottleneck or p-limit for rate limiting:

import pLimit from 'p-limit';

const limit = pLimit(10); // Max 10 concurrent requests

const matches = await Promise.all(
  matchIds.map(matchId =>
    limit(() => client.match.getMatchByMatchId('AMERICAS', matchId)),
  ),
);

Environment Variables

You can store your API key in environment variables:

# .env
RIOT_API_KEY=your_api_key_here

import {RiotClient} from '@zqz979/league-api-wrapper';

const client = new RiotClient({
  apiKey: process.env.RIOT_API_KEY!,
});

TypeScript Support

This library is built with TypeScript and provides complete type definitions for all API responses:

import type {
  SummonerDTO,
  MatchDto,
  Platform,
  Region,
} from '@zqz979/league-api-wrapper';

// All API responses are fully typed
const summoner: SummonerDTO = await client.summoner.getSummonerByEncryptedPUUID(
  'NA1',
  puuid,
);
const match: MatchDto = await client.match.getMatchByMatchId(
  'AMERICAS',
  matchId,
);

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This project is not affiliated with Riot Games. League of Legends is a trademark of Riot Games, Inc.

JSPM

@zqz979/league-api-wrapper