Twisted-Fetch (Fork)

Note: This is a fork of the original twisted library. The primary goal of this fork is to replace the axios dependency with the native fetch API to improve browser/Deno compatibility and reduce bundle size. The original README is preserved below for general reference.

Changes from the original API

Errors and Exceptions thrown

In the event of an error during the fetching of API endpoints, the exceptions that are thrown are not AxiosErrors anymore, but instead GenericErrors, wrapping a FetchError if the API could not access the Riot APIs, a ResponseError if a result could be fetched but the result could not be transformed into an actual Riot Api object (i.e. the status was not in the OK (200-299) range, or the returned json was broken or could not fit into a Twisted DTO object).

FetchError may contain an .error field indicating the original error causing the fetch failure. ResponseError has .status and .headers containing the HTTP status and headers returned by the Riot API servers, and may have a .body with more details. GenericError has .rateLimits indicating the Riot-returned rate limiting parameters and a .error field containing the original error, plus a .status field (with GenericError.UNDEFINED_STATUS = 500 as a default value, so this may not be the actually returned status if the error cause was not an http error response).

Automatic champions ID change detection

constants/champions.ts (and the library) now export new constants and methods to manually start and stop automatic champion ID updates :

DAILY_DELAY: number

UPDATE_CHAMPION_IDS: number

async startChampionUpdates (championUpdateDelay?: number)

stopChampionUpdates ()

async updateChampionIds ()

The startChampionUpdates() function is started automatically if the UPDATE_CHAMPION_IDS env var is set, starting the schedult update like in the original library. But its value now has a meaning : if the env var is set to a number > 0, this number is interpreted as the interval between champion update attempts in seconds and the autoupdate starts. If it is set, but not to a positive number, the DAILY_DELAY value is used instead. As a special case, 1 is used as an equivalent to DAILY_DELAY.

You can check the value of UPDATE_CHAMPION_IDS after the module has been loaded to check which value has been used for the automatic startup delay : 0 means autostart has not been enabled, but you can still call startChampionUpdates manually ; or you could directly call updateChampionIds().

Additional live api tests

Tests in the test/live-api.test.ts suite need an .env file with a RIOT env var RIOT_API_KEY set to a valid API KEY. They perform a couple API calls in order to check everything is working and to test API errors.

Twisted

League of Legends API Wrapper

Simple example

RIOT:

import { RiotApi, Constants } from 'twisted'

const api = new RiotApi()

export async function getAccount () {
  // Recommended to use the nearest routing value to your server: americas, asia, europe
  return (await api.Account.getByRiotId("Hide on bush", "KR1", Constants.RegionGroups.AMERICAS)).response
}

LOL:

import { LolApi, Constants } from 'twisted'

const api = new LolApi()

export async function getSummoner () {
  const user = await getAccount()
  return await api.Summoner.getByPUUID(user.puuid, Constants.Regions.KOREA)
}

TFT:

import { TftApi, Constants } from 'twisted'

const api = new TftApi()

export async function matchListTft () {
  const user = await getAccount()
  return api.Match.list(user.puuid, Constants.RegionGroups.KOREA)
}

More examples

Automatic rate limits reattempts

import { LolApi } from 'twisted'

const api = new LolApi({
   /**
   * If api response is 429 (rate limits) try reattempt after needed time (default true)
   */
  rateLimitRetry: true
  /**
   * Number of time to retry after rate limit response (default 1)
   */
  rateLimitRetryAttempts: 1
  /**
   * Concurrency calls to riot (default infinity)
   * Concurrency per method (example: summoner api, match api, etc)
   */
  concurrency: undefined,
  /**
   * Riot games api key
   */
  key: '',
  /**
   * BaseURL for a rate limiting proxy (default: "https://$(region).api.riotgames.com/:game")
   * Using this field is for a very advanced use case and in most cases not necessary
   * ${region} and :game are expected but not required variables
   */
  baseURL: "http://localhost:8080/${region}/:game",
  /**
   * Debug methods
   */
  debug: {
    /**
     * Log methods execution time (default false)
     */
    logTime: false
    /**
     * Log urls (default false)
     */
    logUrls: false
    /**
     * Log when is waiting for rate limits (default false)
     */
    logRatelimit?: false
  }
})

Endpoints

Everything should be in the same order as in the official docs.

Riot Endpoints

ACCOUNT-V1

Get account by puuid
Get account by puuid - ESPORTS
Get account by riot id
Get account by riot id - ESPORTS
Get active shard for a player
Get active region (lol and tft)
Get account by access token
Get account by access token - ESPORTS

LOL Endpoints

CHAMPION-MASTERY-V4

Get all champion mastery entries sorted by number of champion points descending.
Get a champion mastery by player ID and champion ID.
Get a player's total champion mastery score, which is the sum of individual champion mastery levels.

CHAMPION-V3

Retrieve all champions.
Retrieve champion by ID.

CLASH

MATCH-V5

Get match by id
Get matches by summoner id
Get match timeline by id

MATCH-V4 (deprecated)

LEAGUE-V4

LOL-CHALLENGES-V1

Get all challenge configurations.
Get all challenge percentile distributions.
Get a challenge configuration.
Get Leaderboards for a challenge (Chall, GM, Masters).
Get a challenge percentile distribution.
Get player challenge information.

LOL-STATUS-V3

Get League of Legends status for the given shard.
Get matchlist for games played on given account ID and platform ID and filtered using given filter parameters, if any.
Get match timeline by match ID.
Get match IDs by tournament code.
Get match by match ID and tournament code.

LOL-STATUS-V4

Get League of Legends status for the given platform.

SPECTATOR-V5

Get current game information for the given summoner ID.
Get list of featured games.

SPECTATOR-V4 (deprecated April 5)

Get current game information for the given summoner ID.
Get list of featured games.

SUMMONER-V4

Get a summoner by account ID.
Get a summoner by summoner name. (deprecated Oct 16th, 2023)
Get a summoner by PUUID.
Get a summoner by summoner ID.

TOURNAMENT-STUB-V4

Create a mock tournament code for the given tournament.
Gets a mock list of lobby events by tournament code.
Creates a mock tournament provider and returns its ID.
Creates a mock tournament and returns its ID.

TOURNAMENT-V4

Create a tournament code for the given tournament.
Returns the tournament code DTO associated with a tournament code string.
Update the pick type, map, spectator type, or allowed summoners for a code.
Gets a list of lobby events by tournament code.
Creates a tournament provider and returns its ID.
Creates a tournament and returns its ID.

TFT Endpoints

TFT-SPECTATOR-V5

Get current game information for the given puuid.
Get list of featured games.

TFT-SUMMONER-V1

Get a summoner by account ID.
Get a summoner by summoner name. (deprecated Oct 16th, 2023)
Get a summoner by PUUID.
Get a summoner by summoner ID.

TFT-MATCH-V1

Get match list by summoner PUUID.
Get match list details.

TFT-LEAGUE-V1

Get the challenger league for given queue.
Get the grandmaster league for given queue.
Get the master league for given queue.
Get league entries in all queues for a given summoner ID.
Get all the league entries.
Get league with given ID, including inactive entries.

Run all examples

Download code from git and:

Simple

$ RIOT_API_KEY={YOUR_KEY} yarn example

Specific examples

$ RIOT_API_KEY={YOUR_KEY} yarn example {exampleFunctionName}

With docker

Edit docker-compose.yml with your api key and: $ docker-compose up

Real project

We did a project based on a "twisted" package, this project is not finished but it is a very good example
Github: https://github.com/twisted-gg

Options

The following environment variables can be set either in the .env file or as shown in the examples:

`RIOT_API_KEY`

Obtained from the Riot Games developer page(https://developer.riotgames.com/) Necessary to use this library.

`UPDATE_CHAMPION_IDS`

This library has an option to fetch an actual version of champion IDs regularly. This is useful in case a new champion gets added, while the application runs. E.g. data crawlers, or services which aren't supposed to be restarted regularly.

Set the value to true or 1 to enable this feature.

Name		Name	Last commit message	Last commit date
Latest commit History 381 Commits
.github/workflows		.github/workflows
.vscode		.vscode
example		example
src		src
test		test
.dockerignore		.dockerignore
.eslintrc.cjs		.eslintrc.cjs
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
examples.Dockerfile		examples.Dockerfile
jest.config.js		jest.config.js
package.json		package.json
run-test-fetch.sh		run-test-fetch.sh
runExamples.ts		runExamples.ts
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

License

firstmiddlelast/twisted

Folders and files

Latest commit

History

Repository files navigation