junlarsen/league-connect

League Connect

Module for consume the League of Legends Client APIs
Report Bug | Request Feature

Table of Contents

• Getting Started
  • Prerequisites
  • Installation
• Usage
• License

Getting Started

League Connect is a NodeJs module for consuming the League of Legends Client APIs

• Official League Client API Documentation
• Unofficial League Client API Documentation (HextechDocs)

If you're migrating from v5, please check out the migration guide

Prerequisites

To start using League Connect, ensure the following packages are installed:

• Node (any recent version should run (download))
• Yarn or NPM
• League of Legends (download)

You should also check out the examples directory for code examples.

Installation

League Connect ships as an NPM module, installable through Yarn or NPM. To add the package to your project, install it through your package manager of choice.

$ yarn add league-connect
# Or ...
$ npm install league-connect

Usage

League Connect ships 4 primary APIs:

• authenticate: Fetch credentials to the Client APIs
• LeagueWebSocket: Subscribe to Client API endpoints
• createHttp1/2Request: Send HTTP requests to Client API endpoints
• LeagueClient: Listen for League Client shutdown/startups

Authenticate

Credentials are passed around as an object containing a port and a password (see source). These credentials are pulled from the LeagueClientUx process and will be used to authenticate any requests or connections to the APIs.

Code Example

import { authenticate } from 'league-connect'

const credentials = await authenticate()
console.log(credentials) // { password: '37dn2gsxH3ns', port: 37241 }

By default, the authenticate function will return a rejected promise if it failed to locate a running LeagueClientUx process. If you wish to await until a client is found, you can use the optional options:

import { authenticate } from 'league-connect'

const credentials = await authenticate({
  awaitConnection: true,
  pollInterval: 5000,
  // certificate: "-----BEGIN CERTIFICATE-----\nSowhdnAMyCertificate\n-----ENDCERTIFICATE-----",
  // unsafe: true
})

See source for available options

LeagueWebSocket

The League Client runs a WebSocket for an event bus which anything using the client may connect to. Developers may also connect to this socket over wss. LeagueConnect provides a function to retrieve a WebSocket connection.

import { createWebSocketConnection } from 'league-connect'

const ws = await createWebSocketConnection()

League Connect uses its own extended WebSocket class which allows subscriptions to certain API endpoints.

The socket instance automatically subscribes to Json events from the API which will be ran on the message event.

Code Example

import { createWebSocketConnection } from 'league-connect'

const ws = await createWebSocketConnection({
  authenticationOptions: {
    // any options that can also be called to authenticate()
    awaitConnection: true
  }
})

ws.on('message', message => {
  // Subscribe to any websocket event
})

The createWebSocketConnection function will retry connecting to the WebSocket 10 times by default. A rejected promise will be returned if the function is unable to connect. If you wish to change some of this behavior, you can pass in the following options to the function:

import { createWebSocketConnection } from 'league-connect'

const ws = await createWebSocketConnection({
  authenticationOptions: {
    awaitConnection: true
  },
  pollInterval: 1000,
  maxRetries: 10
})

ws.subscribe('/lol-chat/v1/conversations/active', (data, event) => {
  // data: deseralized json object from the event payload
  // event: the entire event (see EventResponse<T>)
})

See source for available options

Requests

LeagueConnect supports both HTTP/1.1 and HTTP/2.0. Use the corresponding APIs as necessary.

LeagueConnect supports sending HTTP requests to any of the League Client API endpoints (endpoints can be discovered and viewed with LCU Explorer)

If you're looking to use HTTP/2.0, you first need to create a session.

import { authenticate, createHttpSession, createHttp2Request } from 'league-connect'

const credentials = await authenticate()
const session = await createHttpSession(credentials)
const response = await createHttp2Request({
    method: 'GET',
    url: '/lol-summoner/v1/current-summoner'
}, session, credentials)

// Remember to close the session when done
session.close()

For HTTP/1.0, you can simply use the createHttp1Request function.

import { authenticate, createHttp1Request } from 'league-connect'

const credentials = await authenticate()
const response = await createHttp1Request({
    method: 'GET',
    url: '/lol-summoner/v1/current-summoner'
}, credentials)

Both createHttp1Request and createHttp2Request take the same options.

See source for available options

LeagueClient

The LeagueClient class is an EventEmitter which will listen for the LeagueClientUx process, reporting shutdown/startup of the application. The emitter has two listeners: connect and disconnect.

Code Example

import { authenticate, LeagueClient } from 'league-connect'

const credentials = await authenticate()
const client = new LeagueClient(credentials)

client.on('connect', (newCredentials) => {
  // newCredentials: Each time the Client is started, new credentials are made
  // this variable contains the new credentials.
})

client.on('disconnect', () => {

})

client.start() // Start listening for process updates
client.stop()  // Stop listening for process updates

By default, the LeagueClient class will check for a client connection/disconnection every 2.5 seconds. This can be changed by passing an options object into the constructor.

import { authenticate, LeagueClient } from 'league-connect'

const credentials = await authenticate()
const client = new LeagueClient(credentials, {
  pollInterval: 1000 // Check every second
})

See source for available options

License

Distributed under the MIT License. See LICENSE for more information.