Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (samira) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Samira - League of Legends API Library

A TypeScript library for League of Legends API calls with built-in rate limiting, error handling, and type safety.

Features

🚀 Riot Games API Integration - Full support for all major endpoints
⚡ Built-in Rate Limiting - Automatic rate limit handling and retry logic
🛡️ Type Safety - Full TypeScript support with Zod validation
🔄 Regional & Platform Routing - Smart routing for different API endpoints
🎯 Error Handling - Comprehensive error handling with Either types
📦 Data Dragon Integration - Access to League of Legends game assets
🧪 Testing - Comprehensive test suite with Vitest

Installation

npm install samira

Quick Start

import { Samira } from 'samira';

const samira = new Samira({
  apiKey: 'your-riot-api-key',
  platform: 'na1',
  region: 'americas',
});

// Get summoner information
const summoner = await samira.summoner.getSummonerByPuuid('puuid-here');

Configuration

const samira = new Samira({
  apiKey: 'your-riot-api-key',
  platform: 'na1', // or 'euw1', 'kr', etc.
  region: 'americas', // or 'europe', 'asia', 'sea'
  dataDragon: {
    version: 'latest', // or specific version like '13.1.1'
    language: 'en_US', // or 'pt_BR', 'ko_KR', etc.
    includeFullUrl: true, // return full URLs for assets
  },
});

Services

Account Service

// Get account by Riot ID
const account = await samira.account.getAccountByRiotId('GameName', 'TagLine');

// Get account by PUUID
const account = await samira.account.getAccountByPuuid('puuid-here');

Summoner Service

// Get summoner by PUUID
const summoner = await samira.summoner.getSummonerByPuuid('puuid-here');

Match Service

// Get match by ID
const match = await samira.match.getMatchById('match-id-here');

// Get match history
const matchHistory = await samira.match.getMatchHistoryByPUUID('puuid-here');

// Get recent matches
const recentMatches = await samira.match.getRecentMatches('puuid-here', 20);

Spectator Service

// Get active game by PUUID
const activeGame = await samira.spectator.getActiveGameByPuuid('puuid-here');

// Get featured games
const featuredGames = await samira.spectator.getFeaturedGames();

Data Dragon Service

// Get latest game version
const versions = await samira.dataDragon.getLatestVersion();

// Get all champions
const champions = await samira.dataDragon.getChampions();

// Get specific champion
const aatrox = await samira.dataDragon.getChampion('Aatrox');

// Get all items
const items = await samira.dataDragon.getItems();

// Get specific item
const boots = await samira.dataDragon.getItem('1001');

// Get runes
const runes = await samira.dataDragon.getRunes();

// Get summoner spells
const spells = await samira.dataDragon.getSummonerSpells();

Asset URLs

The Data Dragon service provides methods to generate asset URLs:

// Champion images
const championImage = samira.dataDragon.getChampionImageUrl('Aatrox');
const skinImage = samira.dataDragon.getChampionImageUrl('Aatrox', '1'); // Skin ID 1

// Item images
const itemImage = samira.dataDragon.getItemImageUrl('1001');

// Profile icons
const profileIcon = samira.dataDragon.getProfileIconUrl(1);

// Champion splash art
const splashArt = samira.dataDragon.getChampionSplashUrl('Aatrox');
const skinSplash = samira.dataDragon.getChampionSplashUrl('Aatrox', '1');

// Champion loading screens
const loadingScreen = samira.dataDragon.getChampionLoadingUrl('Aatrox');
const skinLoading = samira.dataDragon.getChampionLoadingUrl('Aatrox', '1');

// Rune images
const runeImage = samira.dataDragon.getRuneImageUrl(8000);

// Summoner spell images
const spellImage = samira.dataDragon.getSummonerSpellImageUrl('SummonerFlash');

URL Configuration

You can control whether the service returns full URLs or just asset paths:

// Initialize with full URLs
const samira = new Samira({
  apiKey: 'your-key',
  dataDragon: {
    includeFullUrl: true, // Returns: https://ddragon.leagueoflegends.com/cdn/13.1.1/img/champion/Aatrox.png
  },
});

// Initialize with asset paths only
const samira = new Samira({
  apiKey: 'your-key',
  dataDragon: {
    includeFullUrl: false, // Returns: img/champion/Aatrox.png
  },
});

// Update configuration at runtime
samira.dataDragon.updateConfig({
  includeFullUrl: true,
  language: 'pt_BR',
  version: '13.2.1',
});

Routing

Platform Routing (Game-specific endpoints)

samira.usePlatformRouting(); // Uses platform-specific endpoints
// Examples: /lol/summoner/v4/, /lol/match/v5/, /lol/spectator/v5/

Regional Routing (Account endpoints)

samira.useRegionalRouting(); // Uses regional endpoints
// Examples: /riot/account/v1/

Error Handling

All service methods return Either<ApiError, T> types for robust error handling:

const result = await samira.summoner.getSummonerByPuuid('puuid-here');

if (result.isRight()) {
  // Success case
  const summoner = result.value;
  console.log('Summoner name:', summoner.name);
} else {
  // Error case
  const error = result.value;
  console.error('Error:', error.message);
  console.error('Status:', error.status);
}

Rate Limiting

The library automatically handles Riot Games API rate limits:

// Check rate limit status
const status = samira.getHttpClient().getRateLimitStatus();
console.log('Can make request:', status.canMakeRequest);
console.log('Requests in window:', status.requestsInWindow);
console.log('Delay until next:', status.delayUntilNext);

// Reset rate limiter if needed
samira.getHttpClient().resetRateLimiter();

Testing

Run the test suite:

# Run all tests
npm test

# Run E2E tests
npm run test:e2e

# Run specific test file
npm test -- tests/services/summoner.spec.ts

# Run with coverage
npm run test:coverage

API Reference

Samira Class

constructor(config: SamiraConfig)
getConfig(): SamiraConfig
getHttpClient(): HttpClient
updateApiKey(apiKey: string): void
updatePlatform(platform: string): void
updateRegion(region: string): void
useRegionalRouting(): void
usePlatformRouting(): void

Data Dragon Service

getLatestVersion(): Promise<Either<ApiError, string[]>>
getChampions(version?: string): Promise<Either<ApiError, Record<string, ChampionAsset>>>
getChampion(championId: string, version?: string): Promise<Either<ApiError, ChampionAsset>>
getItems(version?: string): Promise<Either<ApiError, Record<string, ItemAsset>>>
getItem(itemId: string, version?: string): Promise<Either<ApiError, ItemAsset>>
getRunes(version?: string): Promise<Either<ApiError, RuneAsset[]>>
getSummonerSpells(version?: string): Promise<Either<ApiError, Record<string, SummonerSpellAsset>>>
getAssetUrl(assetPath: string): string
getChampionImageUrl(championId: string, skinId?: string): string
getItemImageUrl(itemId: string): string
getProfileIconUrl(iconId: number): string
getChampionSplashUrl(championId: string, skinId?: string): string
getChampionLoadingUrl(championId: string, skinId?: string): string
getRuneImageUrl(runeId: number): string
getSummonerSpellImageUrl(spellId: string): string
updateConfig(config: Partial<DataDragonConfig>): void
getConfig(): DataDragonConfig

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
Submit a pull request

License

MIT License - see LICENSE file for details.