Fateslist.js

An object oriented api wrapper for fateslist written in node.js!

Installation

npm i fateslist.js

Getting started

const Fateslist = require('fateslist.js');
const client = new Fateslist.Client(process.env.FATESLIST_TOKEN);

client.getBot('bot-id').then(console.log);

Remember to always save your token in .env file!

Typescript support

As this package has also typings so you can use it in typescript too!

import Client, { Bot } from 'fateslist.js';

const client: Client = new Client(process.env.FATESLIST_TOKEN);

async function main(){
    const bot: Bot = await client.getBot('bot-id');
    console.log(bot);
}

main();

This package has also raw typings of Fateslist api such as Fateslist.Bot is a classes which is a modified from the raw data of fateslist api whose structure was Fateslist.APIBot!

Error objects

Incase of any error, fateslist will send the Fateslist.APIError object!

interface APIError{
    details?: ({
        loc: string[];
        msg: string;
        type: string;
    }[] | string);
    detail?: string;
}

type APIResponse<T> = APIError | T;

Common Methods

Client.getBot(id: string, compact: boolean): Promise<APIResponse<Bot>>; // Returns a bot information registered in the fateslist database!
Client.getRandomBot(): Promise<CompactBot>; // Returns a random bot in compact form
Client.getVanity(id: string): Promise<APIResponse<APIVanity>>; // Returns the vanity url data
Client.getFeature(id: string): Promise<APIResponse<APIFeature>>; // Returns a feature data by id!
Client.getVoteData(botID: string, userID: string): Promise<APIResponse<VoteData>>; // Returns a vote data of a paticular user to a paticualr bot by id.
Client.getHomeData(): Promise<HomeData>; // Returns the homepage data of fateslist!
Client.getTag(id: string): Promise<Tag>; // Returns a fateslist tag details
Client.getUser(id: string): Promise<APIResponse<User>>; // Returns a fateslist user who has logged in!
Client.search(query: string): Promise<APIResponse<CompactBot[]>>; // Search bots
Client.setDescription(description: string): Promise<APIResponse<boolean>>; // Beta Stage! Sets description for the user!
Client.regenToken(id: string): Promise<APIResponse<boolean>>; // Regenrate your token

Maintenance mode

Set up maintenance mode for your bot easily through js!

const res: Fateslist.APIDoneResponse = await client.setMaintenance('bot-id', {
    mode: true, // True means on and False mean off
    reason: 'Fixing bugs now!'
})

if(!res.done) console.log(res.reason);

// Alternative way using bot object!
bot.setMaintenance({
    mode: true, // True means on and False mean off
    reason: 'Fixing bugs now!'
})

Promotions

Creating, deleting, getting promotions of a bot

Get a promotion

const promotions: Fateslist.Promotion[] = await client.getPromotions('bot-id');

Create a promotion

const res: Fateslist.APIDoneResponse = await client.createPromotion('bot-id', {
    title: 'New announcement',
    info: 'Now you can use out 8ball command!',
    type: Fateslist.promotions.announcement
})

Edit a promotion

const res: Fateslist.APIDoneResponse = await client.editPromotion('bot-id', 'promo-id', {
    title: 'New promotion',
    info: 'We are promoting our new bot ping pong bot!',
    type: Fateslist.promotions.promotion
})

Delete a promotion

const res: Fateslist.APIDoneResponse = await client.deletePromotion('bot-id')

Commands

Add, delete, edit and get commands of your discord bot to the fateslist!

Get commands

const commands: Fateslist.Command[] = await client.getCommands('bot-id');

Add commands

const res: Fateslist.APIDoneResponse<{ id: string }> = await client.addCommand('bot-id', {
    slash: Fateslist.slashTypes.normal, // If its not a slash command
    name: 'Ping Pong',
    description: 'Just my cutie ping pong command',
    args: [],
    examples: ['!pingpong'],
})

Edit commands

const res: Fateslist.APIDoneResponse = await client.editCommand('bot-id', 'command-id', {
    slash: Fateslist.slashTypes.normal, // If its not a slash command
    name: 'Ping Pong',
    description: 'Just my cutie ping pong command! Now only for premium users!',
    args: [],
    examples: ['!pingpong'],
    premiumOnly: true
})

Delete commands

const res: Fateslist.APIDoneResponse = await client.deleteCommand('bot-id', 'command-id');

Posting stats

Post stats through fateslist api

const res: Fateslist.APIDoneResponse = await client.postStats('bot-id', {
    serverCount: 100,
    shardCount: 1,
    shards: [],
    userCount: 20000
})

if(!res.done) console.log(res.reason);

// Alternative way
await bot.postStats({
    serverCount: 100,
    shardCount: 1,
    shards: [],
    userCount: 20000
})

Auto poster

Auto poster automatically posts your guild count easily on intervals which can be paused and stopped too! You need to provide your discord bot client in the first parameter!

const poster: Fateslist.AutoPoster = client.createAutoPoster(client, {
    startOnInitiate: true,
    interval: 900000
})

poster.on('autoPost', () => {
    console.log('[EVENT] => Posted server count!');
})

poster.on('autoPostError', (e) => {
    console.log('[EVENT] => Failed posting count!\n', e);
})

Options

• startOnInitate => Will perform its first post after the class has been initated if true else will wait until it poster.start() has been executed to start its first post! Default: true!
• interval => Interval between each post, must be above than 13 mins! Default: 600000!

Control

poster.stop(); // Will stop posting count
poster.start(); // Will start posting count

Example

For discord.js

const Discord = require('discord.js');
const Fates = require('fateslist.js');
const bot = new Discord.Client();
const client = new Fates.Client('token');
const poster = client.createAutoPoster(bot, { startOnInitiate: false });

bot.on('ready', () => {
    poster.start();
    console.log('[EVENT] => Bot is ready!');
})

bot.login('token');

For eris

const Eris = require('eris');
const Fates = require('fateslist.js');
const bot = new Eris.Client('token');
const client = new Fates.Client('token');
const poster = client.createAutoPoster(bot, { startOnInitiate: false });

bot.on('ready', () => {
    poster.start();
    console.log('[EVENT] => Bot is ready!');
})

bot.connect();

Webhook client

Webhook client is to parse data sent from fateslist and to use it as events using express.js!

const Fates = require('fateslist.js');
const express = require('express.js');
const bodyParser = require('body-parser');
const app = express();
const wh = new Fates.WebhookClient();

app.use(bodyParser.json());
app.post('/webhook', wh.middleware);

wh.on('vote', v => {
    console.log(`${v.voter.username} has voted our bot!`);
})

app.listen(3000);

Events

• vote = (vote: Fateslist.VoteWebhook) => void
• approve = (action: Fateslist.ModAction) => void
• ban = (action: Fateslist.ModAction) => void
• unban = (action: Fateslist.ModAction) => void
• editBot = (action: Fateslist.UserAction) => void
• deleteBot = (action: Fateslist.UserAction) => void
• review = (rev: Fateslist.NewReview) => void
• editReview = (rev: Fateslist.NewReview) => void
• deleteReview = (rev: Fateslist.NewReview) => void
• upvoteReview = (rev: Fateslist.VoteReview) => void
• downvoteReview = (rev: Fateslist.VoteReview) => void

Socket client

Connect to fateslist's socket to interact!

const socket: Fateslist.SocketClient = client.createSocketConnection();

socket.on('ready', () => {
    console.log('Connected to the client!');
})

socket.on('data', (events: Fateslist.WSEvent[]) => {
    events.forEach(x => {
        if(x.name == 'view'){
            console.log(`[EVENT] - Someone has view the bot in fateslist! TYPE: ${x.context.isWidget ? 'WIDGET' : 'USER'}`);
        }
    })
})

socket.on('error', console.log);

socket.on('disconnect', () => {
    console.log('Disconnected to the client!');
})

It might seem like its difficult and yep, it is. Fateslist send array of events in websocket so we need to use this kind of method!

Events

• ready = () => void (Emits when its ready to send and receive data)
• error = (e: Error) => void (Emits when there is an error)
• data = (data: Fateslist.WSEvent[]) => void (Emits when data sent by the fateslist socket api)
• disconnect = () => void (Emits when socket is disconnected)

Event data

interface WSEvent<T = any>{
    name: string; // Event name
    id: string; // ID of the event
    context: T; // Event data
}

Event names will be the name and the context as the parameter as present in the WebhookClient but we will be having one more event in socket that is view with context as structure as

interface View{
    readonly isWidget: boolean;
}

Make an issue if you want to suggest how can we update the socket client!