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

Using Samira (Main Library)

import { Samira } from 'samira';

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

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

Using DataDragon (Game Assets)

import { DataDragon } from 'samira';

const dataDragon = new DataDragon({
  version: 'latest',
  language: 'en_US',
  includeFullUrl: true,
});

// Initialize the service (fetches and caches all data)
await dataDragon.init();

// Get champion information
const champions = await dataDragon.getChampions();
const aatrox = dataDragon.getChampionResumeById(266);

// Get asset URLs
const championImage = dataDragon.getChampionImageUrl('Aatrox');
const itemImage = dataDragon.getItemImageUrl('1001');

Configuration

const samira = new Samira({
  apiKey: 'your-riot-api-key',
  region: 'na1', // or 'euw1', 'kr', etc.
});

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 doransBlade = await samira.dataDragon.getItem(1055);

Types and Schemas

Samira provides comprehensive TypeScript types and Zod schemas for all API responses. You can import and use these types in your own code:

Importing All Types

import {
  // Core types
  Champion,
  Summoner,
  Match,
  LeagueEntry,
  Account,
  CurrentGame,

  // Zod schemas for validation
  ChampionSchema,
  SummonerSchema,
  MatchSchema,
  LeagueEntrySchema,
  AccountSchema,
  CurrentGameSchema,

  // Utility types
  Either,
  Left,
  Right,

  // Constants
  REGIONS,
  PLATFORMS,
  ENDPOINTS,
} from 'samira';

Type Categories

Data Dragon Types

• Champion, Champions - Champion data and lists
• ItemAsset, RuneAsset, SummonerSpellAsset - Game assets
• ChampionInfo, ChampionStats, ChampionSkin, ChampionSpell, ChampionPassive

Account & Summoner Types

• Account - Riot account information
• Summoner - Summoner profile data
• ChampionMastery - Champion mastery information

League Types

• LeagueEntry - Ranked league information
• MiniSeries - Promotion series data
• Rank, Tier - Rank and tier enums

Match Types

• Match, MatchMetadata, MatchInfo - Match data structure
• MatchParticipant - Individual player data
• Challenge, Mission - Advanced match statistics
• MatchTeam, Ban, Objective - Team and objective data

Spectator Types

• CurrentGame - Active game information
• FeaturedGames - Featured games list
• SpectatorParticipant - Player data in spectator mode

Using Zod Schemas for Validation

import { ChampionSchema, MatchSchema } from 'samira';

// Validate API responses at runtime
const champion = ChampionSchema.parse(apiResponse);
const match = MatchSchema.parse(matchData);

// Type-safe data with validation
if (ChampionSchema.safeParse(data).success) {
  // data is now typed as Champion
  console.log(data.name);
}

Error Handling with Either Types

import { Either, Left, Right } from 'samira';

// Handle API responses with type safety
const result: Either<Error, Champion> = await getChampionData();

if (result.isRight()) {
  const champion = result.value; // Type: Champion
  console.log(champion.name);
} else {
  const error = result.value; // Type: Error
  console.error(error.message);
}

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:

```typescript
// 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

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

License

MIT License - see LICENSE file for details.