The Wrapper

Getting Started

Installation

First, we have to install the wrapper, of course. To do so, type the following command in your console:

npm i eztw

Setup

You can also use the command line interface to create an app which is already set up! Just install it and use the create-app command like this:

eztwitch create-app

After that enter your app name and press enter. You're done and you can skip this section. It's as easy as that!

IMPORTANT: See the documentation of the command to see some important notes!

After installing, you have to include the package in your main script file:

const ezTwitch = require('eztw');
const { utils, endpoints } = ezTwitch;
const client = new ezTwitch.client();

We've included our module, our client and extracted the utilities and the endpoints from it. Now we should set our Client ID and our Secret. To do this, we just use the .setID() and .setSecret() method. If you want to, you could also set your token only by using .setToken().

// you can set all of them if you like, or just your token. Please provide ID and Secret, if no token provided.
// all of them
client.setID('your-client-id').setSecret('your-client-secret').setToken('your-token');
// just your token
client.setToken('your-token');
// just client ID and secret
client.setID('your-client-id').setSecret('your-client-secret');
//otherwise it won't work. You can also set token and ID if you like, but that's optional because we validate the token on setup so we get the Client ID from there.

//alternatively on the setup (ONLY ONE OF THESE SOLUTIONS, NOT ALL OF THEM):
const client = new ezTwitch.client("id", "secret", "token");
// to provide the token only just put undefined as first and second argument:
const client = new ezTwitch.client(undefined, undefined, "token");
// or only client ID and secret
const client = new ezTwitch.client("id", "secret");

Now, we should setup our client. To do this, we use the .setup() method:

client.setup();

If you run your script now, it may look like that:

[0/4] ✅ Config fetched!
[1/4][1/3] ✅ Token fetched!
[2/2][2/2] ✅ Token valid!
Setup completed - Welcome to EZ Twitch!

This indicates you've done everything right! Otherwise you'll see an error message with details provided.

The methods

Now, we will walk you through the methods we've provided in our package. They can be used if you've set up your client correctly (as shown in the Getting Started Guide above).

client.reload();

First, client.reload(). It is used to refresh all of your data for API Requests. It is useful if you want to make sure you're using the latest data. If you're using the .setup() method, it's automatically called when the setup is completed.

client.api();

The most useful but most complicated one is the .api() method. It's used to make API requests to the Twitch API.

It takes a string as first argument, which is the method for the request. For example, the GET-Request to get data from the Twitch API.

The second argument is the Endpoint you want to fetch. We automatically provide the https://twitch.tv/api so you just have to type /helix/users for example.

The third argument are the headers of the request. The headers are optional, but if you want to add them, you can do so.

Important: Authorization and Client ID are automatically added to the headers. If you provide them, they will be overwritten. To use them, you have to provide them in the setup or use the setters.

Fetching the API easier

Yeah, you've heard it right. We made some of the work for you so you don't have to search the docs for the Endpoint you actually wanted to fetch. That's why we imported the methods from EZTwitch in the Getting Started Guide! To fetch a user, monstercat for instance, you can do so like this:

client.api("get", endpoints.USERS.GET)

We always recommend to await the request. If you're using it in the main script, you can easily add an anonymous async function like this:

(async () => {
    let res = await client.api("get", endpoints.USERS.GET);
    console.log(res);
})();

We provided every API Endpoint in the endpoints-Object so it's easier for you to use them.

Utilities

Of course we wouldn't want to make an API wrapper without some useful utilities! We've included them in the package and we will include more in future updates. There are some utilities which I used many times before the project was started so I decided to include them ^^

.formatTimestamp()

You fetched the creation date of the account or the stream start timestamp, but you don't know what to do with it? Well, you can format it however you like it to!

Just call the formatTimestamp()-Method from the utils of EZTwitch like this:

utils.formatTimestamp(timestamp, "DD.MM.YYYY, HH:mm:ss")
//                       /\                    /\
//                   Timestamp              Format

.relativeTimestamp()

This method is used to get the relative time from a timestamp. It's useful for displaying the start time of a stream, like it started 3 hours ago.

// it's recommended to use it with the formatTimestamp()-Method like so:
let format = "DD.MM.YYYY, HH:mm:ss";
let timestamp = utils.formatTimestamp(timestamp, format);
let locale = "en";
utils.relativeTimestamp(timestamp, format, locale);

The timestamp and format are self-explanatory. The locale is the language you want to have the relative time in.

.thumbnailSize()

Next up is the thumbnail size! If you don't know, twitch provides the thumbnail URL like so:

https://static-cdn.jtvnw.net/previews-ttv/live_user_monstercat-{width}x{height}.jpg

(Example of Monstercat's stream thumbnail)

That's why we've implemented the thumbnailSize()-Method. It takes the thumbnail URL as first, width as the second and height as the third argument. It returns the URL with the correct size.

Example:

let thumbnail = "https://static-cdn.jtvnw.net/previews-ttv/live_user_monstercat-{width}x{height}.jpg";
let width = 1920;
let height = 1080;
thumbnail = utils.thumbnailSize(thumbnail, width, height);
console.log(thumbnail);

getStreamInfo()

This is the most useful method! It takes the streamer's login as the first argument and your EzTwitch client as the second. It returns an object with the streamers information. Here's an example of how to use it and what it returned:

(async () => {
	let data = await utils.getStreamInfo('monstercat', client);
	console.log(data);
})();

And this is what I got back:

{
  id: '27446517',
  login: 'monstercat',
  display: 'Monstercat',
  broadcasterType: 'partner',
  description: 'Monstercat prides itself in supporting rising electronic artists from around the globe. We are proving that independent labels have the ability to reshape the music industry landscape.',
  profileImage: 'https://static-cdn.jtvnw.net/jtv_user_pictures/monstercat-profile_image-3e109d75f8413319-300x300.jpeg',
  offlineImage: 'https://static-cdn.jtvnw.net/jtv_user_pictures/7d8f79b14cff3966-channel_offline_image-1920x1080.jpeg',
  views: 34750543,
  viewers: 171,
  language: undefined,
  createdAt: '2012-01-15T03:18:08Z',
  startedAt: '2022-01-13T15:00:00Z',
  tagIds: [
    '6ea6bca4-4712-4ab9-a906-e3336a9d8039',
    'c5247b10-deec-4d7a-84a5-db6a75cb5908',
    'd81d54c8-d705-4df6-aaf0-01d715c1dbcc',
    '338d7a92-8bcc-429e-a30c-9f1c41a2d79a',
    '9f1b01a8-87b9-4e25-94de-8705c1c1f4dc'
  ],
  title: 'Non Stop Music - Monstercat TV🎶',
  type: 'live',
  game: 'Music',
  thumbnail: 'https://static-cdn.jtvnw.net/previews-ttv/live_user_monstercat-{width}x{height}.jpg',
  streamId: '44369414076'
}

And that's it!

I hope you like this package. If so, it always motivates me to develop more when you star it on GitHub! Thank you for your support!