Rivals JS

A modern, lightweight, functional, fully typed, and treeshakeable library for interacting with the unofficial Marvel Rivals API.

🚀 Core Ideas

• Fully Typed – code with confidence
• Functional – because classes are so... Java
• Complete Coverage – for the entire Marvel Rivals API
• Lean & Light – no unnecessary bloat

Q&A

How close is this to the API?

The goal for v1 of the library is to align as closely as possible with the API, with only a few differences:

• Everything is camel cased
• The update player endpoint has custom transformation logic as there's 2 different types of responses
• All asset urls are fully qualified

Why functional?

Functional design allows RivalsJS to remain treeshakeable, letting bundlers strip unused code for minimal footprint.

Also because:

• No need to manage class hierarchies
• Just one Axios client to pass around
• Simple testing: input in, output out

Will you ever add a class-based framework?

Maybe, but the core will always remain functional. If we did do a class-based framework it would be part of a bigger piece of the puzzle which we would try to solve on the foundational level first.

A full fledged framework is a huge task and frankly may be outside of the scope of this library.

You already have a v2 wishlist?

Yes! It was the first issue I created. While v1 focuses on building a solid foundation of the library, v2 I want to fix parts of the API that bug me. If there's something you'd like, then throw it on the list!

Getting Started

✅ Before you start

You must have an API key which you can retrieve here. If you have any issues with the API you can join the Discord server.

📦 Installation

npm install rivalsjs  # or
yarn add rivalsjs     # or
bun add rivalsjs

If you're local Node environment is development you will also need to install pino-pretty.

⚡ Jumping In

Creating the client

RivalsJS is designed to be thin, flexible, and functional. We've created a helper function that handles the ground work you need and you pass that Axios client to each function. No blackbox magic here.

import { createRivalsClient } from 'rivalsjs'

// This is just a standard AxiosInstance: https://axios-http.com/docs/instance
const client = createRivalsClient({
  apiKey: 'your-api-key'
})

Example

We support both CJS and ESM, but all examples use ESM. We use neverthrow under the hood, so you can rely on clean control flow using isOk() and isErr(). All functions return Result objects from neverthrow so you always know whether you're working with success or error values. No more try/catch clutter.

import { getHealthCheck } from 'rivalsjs/v1'

const healthcheck = await getHealthCheck(client)

if (healthcheck.isErr()) {
  console.error('An error occurred: ', healthcheck.error)
}

if (healthcheck.isOk()) {
  console.log(healthcheck.value)
  /*
    Output:
    {
      "error": false,
      "message": "Server is healthy",
      "serverTime": "timestamp",
      "serverResponseTime": "0ms",
      "status": 200
    }
  */
}

The same applies to all functions. All functions are documented with JSDoc, so you'll see everything inline in your editor.