Skip to content

A REST client for Fortnite which allows requesting stats, game news and service status from Epic Game's game servers.

Notifications You must be signed in to change notification settings

maxifn/fortnite-client

 
 

Repository files navigation

Fortnite REST Api Client banner

Fortnite REST Client

Build Status npm codecov

A promise based REST client for querying ingame data (such as stats) against the official Fortnite game servers. A valid Fortnite account is required to access these endpoints.

Features

  • Promise based methods to get any Fortnite player's stats
  • Fully OOP and typesafe
  • Throws exceptions if exceeding predefined timeouts or 4xx / 5xx status codes in response.
  • Written in TypeScript (provides always up to date type definitions
  • Covers all publicly accessible endpoints
  • Integration tests
  • No token capturing or similiar needed, just pass your username/pass into the config

And coming up on the roadmap...

  • Event for incoming friend requests 🙋
  • Sending messages to friends 📧
  • Event for incoming friend messages 📥

Table of contents

Getting started

Prerequisites

  • Node.js 8.0+
  • Valid Fortnite account (email and password)
  • Launcher & Client token (can both be sniffed using Fiddler)

Installation

$ npm install --save fortnite-client

Note: Typescript definitions are included, there is no need for installing types from the Definetely Typed Repo.

Basic usage

Typescript (2.0+):

import { FortniteClient, IFortniteClientCredentials, Lookup, PlayerStats } from 'fortnite-client';

const credentials: IFortniteClientCredentials = {
  email: 'weeco91@gmail.com',
  password: 'my-strong-password'
};
const api: FortniteClient = new FortniteClient(credentials);

async function bootstrap(): Promise<void> {
  try {
    await api.login();
    const ninjaLookup: Lookup = await api.lookup('ninja');
    const ninjaStats: PlayerStats = await api.getBattleRoyaleStatsById(ninjaLookup.id);
    console.log(ninjaStats.toJson());
  } catch (err) {
    console.error(err);
  }
}

bootstrap();

Javascript (requires ES6+):

const FortniteClient = require('fortnite-client').FortniteClient;

const credentials = {
  email: 'weeco91@gmail.com',
  password: 'my-strong-password'
};
const api = new FortniteClient(credentials);

async function bootstrap() {
  try {
    await api.login();
    const ninjaLookup = await api.lookup('ninja');
    const ninjaStats = await api.getBattleRoyaleStatsById(ninjaLookup.id);
    console.log(ninjaStats.toJson());
  } catch (err) {
    console.error(err);
  }
}

bootstrap();

Class FortniteClient

The class FortniteClient offers all available endpoints as promise based functions. Each function returns a Promise which resolves to a class instances (e. g. PlayerStats). In order to serialize the data to JSON you can just call the instance's toJson() method, which will return an object.

Instantion

When creating an instance of FortniteClient you can pass a couple options which are described below:

/**
 * Creates a new fortnite client instance.
 * @param credentials The account's credentials which shall be used for the REST requests.
 * @param options Library specific options (such as a response timeout until it throws an exception).
 */
constructor(credentials: IFortniteClientCredentials, options?: IFortniteClientOptions);

export interface IFortniteClientOptions {
  /**
   * Timeout for awaiting a response until it fails. Defaults to 5000 milliseconds.
   */
  timeoutMs?: number;
  /**
   * Tunnel requests through a proxy of your choice. If you want to inspect requests with Fiddler you have to
   * setup the proxy here.
   */
  proxy?: IProxyOptions;
}

export interface IProxyOptions {
  host: string;
  port: number;
}

Available endpoints

Route Returns
static CHECK_STATUS() Promise<ICheckStatus[]>
static GET_GAME_NEWS() Promise<IGameNews>
login() Promise<void>
getBattleRoyaleStatsById(userId: string, timeWindow: TimeWindow, convertJSONOutput: boolean=true) Promise<IPlayerStats>
getStore(locale: string = 'en-US') Promise<IStore>
getLeaderboards(leaderboardType: LeaderboardType, platform: Platform, groupType: GroupType, timeWindow: TimeWindows, limit: number = 50) Promise<ILeaderboards>
lookup(username: string) Promise<ILookup>
lookupByIds(accountIds: string[]) Promise<Map<string, ILookup>>

Class LauncherClient

The class LauncherClient offers some of the endpoints (which I considered as useful) made by the Epic Games Launcher.

Instantion

When creating an instance of LauncherClient you can pass a couple options which are the same as described in FortniteClient Instantion.

Available endpoints

Route Returns
buildInformation() Promise<BuildInformation>

Contributors

SkYNewZ (https://github.com/SkYNewZ) - Primarily helped with the Git setup including Travis CI & Code coverage reports

Contributions to the code or documentation are welcome. If you want to add a new feature please open an issue before.

License

The MIT License (MIT)

Copyright (c) 2018 Weeco

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

About

A REST client for Fortnite which allows requesting stats, game news and service status from Epic Game's game servers.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • TypeScript 100.0%