Home

Installation

You can install the official node sdk via

npm i @top-gg/sdk or yarn add @top-gg/sdk

Examples

You can find examples on the NPM Package page

Change Log

3.0.4

• Released official documentation page

• Added GitHub actions to publish to npm on release

3.0.3

• Fixed some webhook bugs

• Improved a few typings

3.0.2

Some day-one patches to README, 3.0.1 is a dud release

3.0.0

A full rewrite of the package, here’s some of the major changes:

• The webhook and API interaction have been full separated, into two different classes, Api and Webhook

• Auto-Posting is no longer natively supported in the package, instead you can use the officially supported topgg-autoposter package.

• The webhook class is no longer ran off of events, instead acting as a middleware function that defines req.vote

Api

Top.gg API Client for Posting stats or Fetching data

Kind: global classLink: https://top.gg/api/docs

• Api

  • new Api(token, options)

  • .postStats(stats) ⇒ BotStats

  • .getStats(id) ⇒ BotStats

  • .getBot(id) ⇒ BotInfo

  • .getUser(id) ⇒ UserInfo

  • .getBots(query) ⇒ BotsResponse

  • .getVotes() ⇒ Array.<ShortUser>

  • .hasVoted(id) ⇒ Boolean

  • .isWeekend() ⇒ Boolean

new Api(token, options)

Create Top.gg API instance

Param	Type	Description
token	string	Token or options
options	object	API Options

Example

const Topgg = require(`@top-gg/sdk`)

const api = new Topgg.Api('Your top.gg token')

api.postStats(stats) ⇒ BotStats

Post bot stats to Top.gg (Do not use if you supplied a client)

Kind: instance method of ApiReturns: BotStats - Passed object

Param	Type	Description
stats	Object	Stats object
stats.serverCount	number	Server count
stats.shardCount	number	Shard count
stats.shardId	number	Posting shard (useful for process sharding)

Example

await client.postStats({
  serverCount: 28199,
  shardCount: 1
})

api.getStats(id) ⇒ BotStats

Get a bots stats

Kind: instance method of ApiReturns: BotStats - Stats of bot requested

Param	Type	Description
id	Snowflake	Bot ID

Example

await client.getStats('461521980492087297')
// =>
{
  serverCount: 28199,
  shardCount 1,
  shards: []
}

api.getBot(id) ⇒ BotInfo

Get bot info

Kind: instance method of ApiReturns: BotInfo - Info for bot

Param	Type	Description
id	Snowflake	Bot ID

Example

await client.getBot('461521980492087297') // returns bot info

api.getUser(id) ⇒ UserInfo

Get user info

Kind: instance method of ApiReturns: UserInfo - Info for user

Param	Type	Description
id	Snowflake	User ID

Example

await client.getUser('205680187394752512')
// =>
user.username // Xignotic

api.getBots(query) ⇒ BotsResponse

Get a list of bots

Kind: instance method of ApiReturns: BotsResponse - Return response

Param	Type	Description
query	BotsQuery	Bot Query

Example

// Finding by properties
await client.getBots({
  search: {
    username: 'shiro',
    certifiedBot: true
    ...any other bot object properties
  }
})
// =>
{
  results: [
    {
      id: '461521980492087297',
      username: 'Shiro',
      discriminator: '8764',
      lib: 'discord.js',
      ...rest of bot object
    }
    ...other shiro knockoffs B)
  ],
  limit: 10,
  offset: 0,
  count: 1,
  total: 1
}
// Restricting fields
await client.getBots({
  fields: ['id', 'username']
})
// =>
{
  results: [
    {
      id: '461521980492087297',
      username: 'Shiro'
    },
    {
      id: '493716749342998541',
      username: 'Mimu'
    },
    ...
  ],
  ...
}

api.getVotes() ⇒ Array.<ShortUser>

Get users who’ve voted

Kind: instance method of ApiReturns: Array.<ShortUser> - Array of users who’ve votedExample

await client.getVotes()
// =>
[
  {
    username: 'Xignotic',
    discriminator: '0001',
    id: '205680187394752512',
    avatar: '3b9335670c7213b3a2d4e990081900c7'
  },
  {
    username: 'iara',
    discriminator: '0001',
    id: '395526710101278721',
    avatar: '3d1477390b8d7c3cec717ac5c778f5f4'
  }
  ...more
]

api.hasVoted(id) ⇒ Boolean

Get whether or not a user has voted

Kind: instance method of ApiReturns: Boolean - Whether the user has voted

Param	Type	Description
id	Snowflake	User ID

Example

await client.hasVoted('205680187394752512')
// => true/false

api.isWeekend() ⇒ Boolean

Whether or not the weekend multiplier is active

Kind: instance method of ApiReturns: Boolean - Whether the the multiplier is activeExample

await client.hasVoted()
// => true/false

Webhook

Top.gg Webhook

Kind: global class

• Webhook

  • new Webhook(authorization)

  • .middleware()

new Webhook(authorization)

Create a new webhook client instance

Param	Description
authorization	Webhook authorization to verify requests

Example

const express = require('express')
const { Webhook } = require(`@top-gg/sdk`)

const app = express()
const wh = new Webhook('webhookauth123')

app.post('/dblwebhook', wh.middleware(), (req, res) => {
  // req.vote is your vote object e.g
  console.log(req.vote.user) // => 321714991050784770
})

app.listen(80)

// In this situation, your TopGG Webhook dashboard should look like
// URL = http://your.server.ip:80/dblwebhook
// Authorization: webhookauth123

webhook.middleware()

Middleware function to pass to express, sets req.vote to the payload

Kind: instance method of WebhookExample

app.post('/dblwebhook', wh.middleware(), (req, res) => {
  // req.vote is your payload e.g
  console.log(req.vote.user) // => 395526710101278721
})