Skip to content

Latest commit

 

History

History
1098 lines (784 loc) · 33 KB

api.md

File metadata and controls

1098 lines (784 loc) · 33 KB
Raw

Classes

Client

The main Client object

Collection ⇐ Map

Hold a bunch of something

Ban

Represents a ban

Booth

Represents a rooms booth settings

ExtendedUser

An user with more information

Media

Represents a media object

Message

Represents a single chat message

MinimalUser

An user with the minimum of information plug gives

Playback

Represents a Play

Queue

Represents the queue of a room

Room

Represents a room

User

Represents a user.

Client

The main Client object

Kind: global class
Properties

Name Type Description
ready Boolean Indicates if the client is ready for rest calls.
room Room The current room
socketStatus String The current status of the socket connection
self ExtendedUser The logged-in user

new Client(email, password, [options])

Create a new Client

Param Type Default Description
email String The Email to use for login
password String the password to use
[options] Object An object containing additional settings
[options.useFriends] Boolean false Whether the bot should distinguish between friends or not
[options.autoConnect] Boolean false If the bot should automatically establish a socket connection
[options.autoReconnect] Boolean false If the bot should automatically reopen an errored or closed socket connection
[options.requestFreeze] Number 1000 The time all requests are freezed when a ratelimit warning is received. Can not be lower than 1
[options.chatFreeze] Number 1000 The time all chatmessages are freezed when receiving a "floodChat" event
[options.ignoreRateLimits] Boolean false Whether to respect plug.dj's rate limits or not. It's not recommended to use this option except when you are having your own handling for rate limits.
[options.updateNotification] Boolean false Whether you want to notified about (possible) updates.

client.connect() ⇒ Promise

Establishes the Websocket Conncetion to plug.dj

Kind: instance method of Client

client.joinRoom(slug) ⇒ Promise

Joins a room (community)

Kind: instance method of Client

Param Type Description
slug String the slug to join

client.sendChat(content) ⇒ Promise

Sends a message in chat

Kind: instance method of Client

Param Type Description
content String The message content

client.banUser(userID, [time], [reason]) ⇒ Promise

Bans an user from the room.

Kind: instance method of Client

Param Type Default Description
userID Number The id of the user
[time] String 'd' The ban duration, defaults to one day ('h' for one hour, 'd' for a day, 'f' for forever)
[reason] Number 1 The ban reason, defaults to 'violating community rules'

client.unbanUser(userID) ⇒ Promise

Removes a ban for a user

Kind: instance method of Client

Param Type Description
userID Number The id of the user

client.skipSong([userID], [historyID]) ⇒ Promise

Skips the current playback. All fields are automatically filled in, however it is recommended to provide at least the userID to prevent wrong skips

Kind: instance method of Client

Param Type Description
[userID] Number The id of the current dj
[historyID] String The id of the current playback

client.deleteMessage(chatID) ⇒ Promise

Deletes a chat message

Kind: instance method of Client

Param Type Description
chatID String Id of the message to be deleted

client.setRole(userID, role) ⇒ Promise

Sets an user as staff

Kind: instance method of Client

Param Type Description
userID Number
role Number the role, 0 for grey, 1 for res dj, 2 for bouncer, 3 for manager, 4 for co-host, 5 for host

client.removeRole(userID) ⇒ Promise

Shorthand for {Client}.setRole(userID, 0)

Kind: instance method of Client

Param Type
userID Number

"ready"

Emitted when the client is ready to make rest calls

Kind: event emitted by Client

"joinedRoom"

Emitted when a room was joined and the caches were filled.

Kind: event emitted by Client

"socketError"

Emitted when the socket errors

Kind: event emitted by Client

"socketClose"

Emitted when the socket is closed

Kind: event emitted by Client
Properties

Name Type Description
data.code Number The close code.
data.reason String A human-readable close reason.

"rawWS"

Emits the raw packages.

Kind: event emitted by Client
Properties

Name Type Description
data Object The data received from plug.dj

"unknown"

Emitted when an unknown package is received from plug. This can indicate an outdated version of plugging-you-in

Kind: event emitted by Client

"connect"

Emitted when the socket connection is up.

Kind: event emitted by Client
Properties

Name Type Description
room String The room the client is currently in

"chat"

Emitted when a chat message is received

Kind: event emitted by Client
Properties

Name Type Description
message Message The received message

"chatDelete"

Emitted when a moderator deletes a chat message

Kind: event emitted by Client
Properties

Name Type Description
message Message The deleted message (can be null if message is not cached)
The User user who deleted the message

"guestJoin"

Emitted when a guest joins the room

Kind: event emitted by Client

"userJoin"

Emitted when an users joins the room

Kind: event emitted by Client
Properties

Name Type Description
user User The joined user

"friendJoin"

Emitted when an users joins the room

Kind: event emitted by Client
Properties

Name Type Description
user User The joined user

"guestLeave"

Emitted when a guest leaves the room

Kind: event emitted by Client

"userLeave"

Emitted when an user leaves the room.

Kind: event emitted by Client
Properties

Name Type Description
user User The left user

"advance"

Emitted when a new song is played

Kind: event emitted by Client
Properties

Name Type Description
playback Playback The current playback
oldPlayback Playback The playback before.

"queueUpdate"

Emitted when the waitlist changes

Kind: event emitted by Client
Properties

Name Type Description
queue Array.<User> The new queue as an array of users
oldQueue Array.<User> The old queue

"cycleChange"

Emitted when the cycle-mode gets changed

Kind: event emitted by Client
Properties

Name Type Description
user User The user who changed the cycle mode
state Boolean The new cycle-mode

"lockChange"

Emitted when the queue gets locked/unlocked/cleared

Kind: event emitted by Client
Properties

Name Type Description
user User The user who took the action
lock Boolean The new lock-state of the queue
clear Boolean Wheter the queue got cleared or not

"vote"

Emitted when someone votes on a song

Kind: event emitted by Client
Properties

Name Type Description
user User The user who voted
vote Number The vote, 1 for woot, -1 for meh

"grab"

Emitted when an user grabs a song

Kind: event emitted by Client
Properties

Name Type Description
user User The user who grabbed the song

"floodApi"

Emitted when too many api requests are fired. You don't need to handle it if you leave options.requestFreeze at the default value, however all actions will be stopped for 10 seconds

Kind: event emitted by Client

"floodChat"

Emitted when you are sending too many chat messages and plugging-you-in isn't good enough at limiting you. Plugging-you-in will handle this by stopping to send messages entirely for a few seconds

Kind: event emitted by Client

"slowMode"

Emitted when chat enters slow mode.

Kind: event emitted by Client

"earn"

Emitted when the bot earns experience/plug points or levels up

Kind: event emitted by Client
Properties

Name Type Description
earn Object
earn.xp Number The new amount of xp
earn.pp Number The new amount of plug points
earn.level Number The new level

"gifted"

Emitted when someone gifts plug points to someone

Kind: event emitted by Client
Properties

Name Type Description
sender User The user who sent the gift
receiver User The user who received the gift

"ban"

Emitted when you are banned from a community

Kind: event emitted by Client
Properties

Name Type Description
ban Ban The ban object

"addDj"

Emitted when a moderator adds someone to the queue. This also fires a queueUpdate-event

Kind: event emitted by Client
Properties

Name Type Description
user User The user who got added
moderator User The Moderator

"userBan"

Emitted when a moderator bans someone from the room

Kind: event emitted by Client
Properties

Name Type Description
ban Ban The ban
moderator User

"moveUser"

Emitted when a moderator moves someone in the queue. This also fires a queueUpdate-event

Kind: event emitted by Client
Properties

Name Type Description
user User The moved user
moderator User
newPosition Number
oldPosition Number

"skip"

Emitted when a moderator skips a song

Kind: event emitted by Client
Properties

Name Type
moderator User

"killSession"

Emitted when the socket server kills the session

Kind: event emitted by Client

"error"

Emitted when the client encounters an error which it cannot handle itself

Kind: event emitted by Client
Properties

Name Type Description
error String | Error The error or an error message.
err Error An error object

"levelUp"

Emitted when the logged in account levels up

Kind: event emitted by Client
Properties

Name Type
newLevel Number

"maintenance"

Emitted when plug.dj goes into maintenance mode

Kind: event emitted by Client

"maintenanceAlert"

Emitted when plug.dj is about to go into maintenance mode

Kind: event emitted by Client
Properties

Name Type Description
time Number time til maintenance mode in minutes

"plugMessage"

Emitted when plug.dj sends a broadcast

Kind: event emitted by Client
Properties

Name Type
message String

"plugUpdate"

Emitted when plig.dj gets updated.

Kind: event emitted by Client

"selfSkip"

Emitted when someone skips himself

Kind: event emitted by Client
Properties

Name Type
user User

Collection ⇐ Map

Hold a bunch of something

Kind: global class
Extends: Map
Properties

Name Type Description
baseObject Class The base class for all items
limit Number Max number of items to hold

new Collection(baseObject, [limit])

Construct a Collection

Param Type Description
baseObject Class The base class for all items
[limit] Number Max number of items to hold

collection.add(obj, extra, replace) ⇒ Class

Add an object

Kind: instance method of Collection
Returns: Class - The existing or newly created object

Param Type Description
obj Object The object data
obj.id String The ID of the object
extra Class An extra parameter the constructor may need
replace Boolean Whether to replace an existing object with the same ID

collection.find(func) ⇒ Class

Return the first object to make the function evaluate true

Kind: instance method of Collection
Returns: Class - The first matching object, or undefined if no match

Param Type Description
func function A function that takes an object and returns true if it matches

collection.random() ⇒ Class

Get a random object from the Collection

Kind: instance method of Collection
Returns: Class - The random object, or undefined if there is no match

collection.filter(func) ⇒ Array.<Class>

Return all the objects that make the function evaluate true

Kind: instance method of Collection
Returns: Array.<Class> - An array containing all the objects that matched

Param Type Description
func function A function that takes an object and returns true if it matches

collection.map(func) ⇒ Array

Return an array with the results of applying the given function to each element

Kind: instance method of Collection
Returns: Array - An array containing the results

Param Type Description
func function A function that takes an object and returns something

collection.update(obj, extra, replace) ⇒ Class

Update an object

Kind: instance method of Collection
Returns: Class - The updated object

Param Type Description
obj Object The updated object data
obj.id String The ID of the object
extra Class An extra parameter the constructor may need
replace Boolean Whether to replace an existing object with the same ID

collection.remove(obj) ⇒ Class

Remove an object

Kind: instance method of Collection
Returns: Class - The removed object, or null if nothing was removed

Param Type Description
obj Object The object
obj.id String The ID of the object

Ban

Represents a ban

Kind: global class
Properties

Name Type Description
duration String The ban duration ('h' for one hour, 'd' for a day, 'f' for forever)

ban.remove() ⇒ Promise

Removes this ban.

Kind: instance method of Ban

Booth

Represents a rooms booth settings

Kind: global class
Properties

Name Type Description
isLocked Boolean Whether the queue is lock or unlocked
shouldCycle Boolean Whether the queue cycles or not

booth.unlock() ⇒ Promise

Unlocks the queue

Kind: instance method of Booth

booth.lock() ⇒ Promise

Locks the queue

Kind: instance method of Booth

booth.clear() ⇒ Promise

Clears and locks the queue

Kind: instance method of Booth

booth.enableCycle() ⇒ Promise

Enables queue cycling

Kind: instance method of Booth

booth.disableCycle() ⇒ Promise

Disables queue cycling

Kind: instance method of Booth

ExtendedUser

An user with more information

Kind: global class
Properties

Name Type Description
settings Object An object containing settings
plugPoints Number The current amount of plug points the user has
xp Number The current number of experience points the user has
ignores Array.<MinimalUser> An array of users the current user ignores

Media

Represents a media object

Kind: global class
Properties

Name Type Description
id Number The unique id used by plug
cid String The id used by the source. This is only unique if used together with 'format'
format Number The format of the media. 1 is YouTube, 2 is SoundCloud
author String The media author
title String The media title
duration Number The media duration
image String A link to a cover image.
name String The concatenated name of the media
uniqueId String An unique id for the media

Message

Represents a single chat message

Kind: global class
Properties

Name Type Description
content String The message content.
user User The user who sent the message.
time Date The time the message was received.
mentioned Boolean Indicates if the bot was mentioned

message.delete() ⇒ Promise

Deletes this message

Kind: instance method of Message

MinimalUser

An user with the minimum of information plug gives

Kind: global class
Properties

Name Type Description
id Number The id of the user.
username String The name of the user

minimalUser.ban(time, reason) ⇒ Promise

Bans the user from the community

Kind: instance method of MinimalUser

Param Type
time String
reason Number

minimalUser.unban() ⇒ Promise

Unbans the user from the community

Kind: instance method of MinimalUser

minimalUser.setRole(role) ⇒ Promise

Sets the user as staff

Kind: instance method of MinimalUser

Param Type Description
role Number the role, 0 for grey, 1 for res dj, 2 for bouncer, 3 for manager, 4 for co-host, 5 for host

minimalUser.removeRole() ⇒ Promise

Shorthand for {MinimalUser}.setStaff(0)

Kind: instance method of MinimalUser

Playback

Represents a Play

Kind: global class
Properties

Name Type Description
id String The current history id
timestamp String The timestamp when the playback started
media Media The media played
user User The dj

Queue

Represents the queue of a room

Kind: global class
Properties

Name Type Description
queue Array.<User> An ordered array of users being in the queue

queue.addUser(userID) ⇒ Promise

Adds an user to the queue

Kind: instance method of Queue

Param Type Description
userID Number The id of the user to add

queue.removeUser(userID) ⇒ Promise

Removes an user from the queue

Kind: instance method of Queue

Param Type Description
userID Number The id of the user to be removed

queue.moveUser(userID, position) ⇒ Promise

Moves an user in the queue

Kind: instance method of Queue

Param Type Description
userID Number The user to move
position Number The new position of the user

queue.lock() ⇒ Promise

Locks the queue

Kind: instance method of Queue

queue.unlock() ⇒ Promise

Unlocks the queue

Kind: instance method of Queue

queue.clear() ⇒ Promise

Clears and locks the queue

Kind: instance method of Queue

Room

Represents a room

Kind: global class
Properties

Name Type Description
id Number The room id
slug String The room slug
name String The room name
welcomeMessage String The welcome message
description String The room description
minChatLevel Number The minimal level required to chat

User

Represents a user.

Kind: global class
Properties

Name Type Description
role Number The role of the user
globalRole Number The global role of the user (e.g. Brand Ambassador, Admin)
avatarID String The avatar of the user
badge String The badge of the user
subscription String The subscription type of the user
guest Boolean Whether the user is a guest or not
joined Date When the user created his/her account
language String The users language
blurb String The users profile description
slug String A flattend and url-friendly version of the username
level Number The level of the user
mention String The mention for that user

user.mute(time, reason) ⇒ Promise

Mutes the user

Kind: instance method of User

Param Type
time Number
reason String

user.move(position) ⇒ Promise

Moves the user in the waitlist

Kind: instance method of User

Param Type
position Number

user.add() ⇒ Promise

Adds the user to the waitlst

Kind: instance method of User

user.remove() ⇒ Promise

Removes the user from the waitlist

Kind: instance method of User