TypeScript-first Riot Games API wrapper for Node.js, with built-in Data Dragon support.

What this package does

RiftJS wraps common Riot API and Data Dragon use cases in a small API:

• Resolve account details from Riot ID
• Get summoner details from PUUID
• Get rank entries and queue-split rank summaries
• Get match IDs, match details, and match timelines
• Fetch all match IDs with paging and optional pacing
• Fetch Data Dragon champion and item static data

The package is authored in TypeScript and published as compiled CommonJS with .d.ts types.

Install

npm install @timmsy/riftjs

You need a Riot developer key:

• https://developer.riotgames.com/

Quick Start

1. Configure environment

Create a .env file in your app:

RIOT_API_KEY=RGAPI-your-key-hereREGION=EUW1

Notes:

• RIOT_API_KEY is required for RiotAPI.
• REGION is optional. Default is EUW1.

2. Basic usage (JavaScript / CommonJS)

const{ RiotAPI, DataDragon }=require('@timmsy/riftjs');asyncfunctionmain(){constriot=newRiotAPI();constaccount=awaitriot.getAccountByRiotId('PlayerName#EUW');constsummoner=awaitriot.getSummonerByPuuid(account.puuid);constmatchIds=awaitriot.getMatchlistByPuuid(account.puuid,{start: 0,count: 5});console.log('Summoner level:',summoner.summonerLevel);console.log('Recent matches:',matchIds);constdd=newDataDragon();constchampions=awaitdd.getChampions();console.log('Champion count:',Object.keys(champions.data||{}).length);}main().catch((err)=>{console.error(err.message);process.exitCode=1;});

3. Basic usage (TypeScript)

import{RiotAPI,DataDragon}from'@timmsy/riftjs';asyncfunctionmain(): Promise<void>{constriot=newRiotAPI();constaccount=awaitriot.getAccountByRiotId('PlayerName#EUW');constrank=awaitriot.getRankByPuuid(String(account.puuid||''));console.log('Solo queue:',rank.solo);console.log('Flex queue:',rank.flex);constdd=newDataDragon();constitems=awaitdd.getItems();console.log('Item count:',Object.keys((items.dataasRecord<string,unknown>)||{}).length);}main().catch((err: unknown)=>{constmessage=errinstanceofError ? err.message : 'Unknown error';console.error(message);process.exitCode=1;});

API Reference

RiotAPI

new RiotAPI() reads:

• RIOT_API_KEY from environment
• REGION from environment (default EUW1)

getAccountByRiotId(riotId, tagLine?, region?)

• Input:
  • riotId: string ("Name#Tag" format, or name-only with tagLine)
  • tagLine?: string | null
  • region?: RegionCode
• Output: account payload (includes puuid)
• Example:

constaccount=awaitriot.getAccountByRiotId('Timmsy#BRUV');

getSummonerByPuuid(puuid, region?)

• Input:
  • puuid: string
  • region?: RegionCode
• Output: Summoner V4 payload

getRankEntriesByPuuid(puuid, region?)

• Input:
  • puuid: string
  • region?: RegionCode
• Output: League V4 rank entries array

getRankByPuuid(puuid, region?)

• Input:
  • puuid: string
  • region?: RegionCode
• Output:
  • solo: solo queue entry with computed winRate (or null)
  • flex: flex queue entry with computed winRate (or null)
  • entries: original rank entries

Queue constants used internally:

• RANKED_SOLO_5x5
• RANKED_FLEX_SR

getMatchlistByPuuid(puuid, options?, region?)

• Input:
  • puuid: string
  • options?: MatchlistOptions
  • region?: RegionCode
• Output: string[] of match IDs

MatchlistOptions:

• startTime?: number (epoch seconds)
• endTime?: number (epoch seconds)
• queue?: number
• type?: string
• start?: number
• count?: number (Riot max is 100 for this endpoint)

getMatchById(matchId, region?)

• Input:
  • matchId: string (example EUW1_1234567890)
  • region?: RegionCode
• Output: Match V5 payload (metadata + info)

getMatchTimelineById(matchId, region?)

• Input:
  • matchId: string
  • region?: RegionCode
• Output: Match timeline payload

getMatchlistByPuuidAll(puuid, options?, region?, pacing?)

• Purpose: fetches all match IDs in pages of up to 100.
• Input:
  • puuid: string
  • options?: MatchlistOptions (filters + optional start offset)
  • region?: RegionCode
  • pacing?: { delayMs?: number; maxMatches?: number | null }
• Output: string[] of aggregated match IDs

getMatchesWithDetailsByPuuid(puuid, options?, region?, pacing?)

• Purpose: fetches match IDs, then fetches each match payload.
• Input:
  • puuid: string
  • options?: MatchlistOptions
  • region?: RegionCode
  • pacing?: { pageDelayMs?: number; detailDelayMs?: number; maxMatches?: number | null }
• Output:
  • matchIds: string[]
  • matches: object[]

DataDragon

new DataDragon(version?, locale?)

• version?: string | null
  • Omit to auto-resolve the latest Data Dragon version
  • Pass a version like 15.4.1 to pin
• locale?: string
  • Defaults to en_US

getChampions()

• Output: Data Dragon champion payload (champion.json)

getItems()

• Output: Data Dragon item payload (item.json)

Supported regions

Supported REGION / region values:

BR1, EUN1, EUW1, JP1, KR, LA1, LA2, NA1, OC1, TR1, RU, PH2, SG2, TH2, TW2, VN2

Routing behavior:

• Platform APIs (example Summoner V4) use platform hosts like euw1.api.riotgames.com.
• Regional APIs (example Match V5 / Account V1) use shard hosts like europe.api.riotgames.com.

Error behavior

RiftJS normalizes errors to plain Error objects with readable messages:

• HTTP response errors: API error <status>: <message>
• No response from Riot: No response received from the server
• Request setup/other errors: Request error: <message>
• Data Dragon wrapper errors: DataDragon error: <message>

Local development

Run locally

git clone https://github.com/timmsy1998/RiftJS.git
cd RiftJS
npm install
npm run build

Run endpoint checks

npm test

Test script behavior:

• Riot endpoint checks run only when RIOT_API_KEY and TEST_RIOT_ID are set.
• Data Dragon checks always run.

Optional .env values for tests:

TEST_RIOT_ID=YourRiotNameTEST_TAG_LINE=EUW

Maintainer notes:

• See MAINTAINER_NOTES.md for project conventions and release checklist.

Package output

Published entry points:

• main: dist/index.js
• types: dist/index.d.ts

Build command:

npm run build

Compiled output is written to dist/.

License

MIT License © 2025 James Timms. See LICENSE.

Links

• npm: https://www.npmjs.com/package/@timmsy/riftjs
• GitHub: https://github.com/timmsy1998/RiftJS
• Riot Developer Portal: https://developer.riotgames.com/