From 7144ead04829a3a8baf2bda4ee80c1152dd215fe Mon Sep 17 00:00:00 2001 From: hydrabolt Date: Sat, 13 Feb 2016 18:21:59 +0000 Subject: [PATCH] docs 6.66% --- lib/Client/Client.js | 472 +++++++++++++++++++++++++++++--- lib/Client/Resolver/Resolver.js | 25 ++ lib/Structures/Message.js | 6 + lib/Util/TokenCacher-shim.js | 24 +- lib/Voice/VoicePacket.js | 26 +- lib/index.js | 60 +++- src/Client/Client.js | 78 +++++- src/Client/Resolver/Resolver.js | 12 + src/Structures/Server.js | 5 + test/msgbot.js | 4 +- 10 files changed, 628 insertions(+), 84 deletions(-) diff --git a/lib/Client/Client.js b/lib/Client/Client.js index 75a361733..2ebdaa0fb 100644 --- a/lib/Client/Client.js +++ b/lib/Client/Client.js @@ -42,13 +42,22 @@ function dataCallback(callback) { }; } +/** + * Used to interface with the Discord API. + */ + var Client = (function (_EventEmitter) { _inherits(Client, _EventEmitter); - /* - this class is an interface for the internal - client. - */ + /** + * Used to instantiate Discord.Client + * @param {ClientOptions} [options] options that should be passed to the Client. + * @example + * // creates a new Client that will try to reconnect whenever it is disconnected. + * var client = new Discord.Client({ + * revive : true + * }); + */ function Client() { var options = arguments.length <= 0 || arguments[0] === undefined ? {} : arguments[0]; @@ -56,15 +65,55 @@ var Client = (function (_EventEmitter) { _classCallCheck(this, Client); _EventEmitter.call(this); + /** + * Options that were passed to the client when it was instantiated. + * @readonly + * @type {ClientOptions} + */ this.options = options || {}; this.options.compress = options.compress || !process.browser; this.options.revive = options.revive || false; this.options.rate_limit_as_error = options.rate_limit_as_error || false; this.options.large_threshold = options.large_threshold || 250; + /** + * Internal Client that the Client wraps around. + * @readonly + * @type {InternalClient} + */ this.internal = new _InternalClient2["default"](this); } - // def loginWithToken + /** + * The users that the Client is aware of. Only available after `ready` event has been emitted. + * @type {Cache} a Cache of the Users + * @readonly + * @example + * // log usernames of the users that the client is aware of + * for(var user of client.users){ + * console.log(user.username); + * } + */ + + /** + * Log the client in using a token. If you want to use methods such as `client.setUsername` or `client.setAvatar`, you must also pass the email and password parameters. + * @param {string} token A valid token that can be used to authenticate the account. + * @param {string} [email] Email of the Discord Account. + * @param {string} [password] Password of the Discord Account. + * @param {function(err: Error, token: string)} [callback] callback callback to the method + * @returns {Promise} Resolves with the token if the login was successful, otherwise it rejects with an error. + * @example + * // log the client in - callback + * client.login("token123", null, null, function(error, token){ + * if(!error){ + * console.log(token); + * } + * }); + * @example + * // log the client in - promise + * client.login("token123") + * .then(token => console.log(token)) + * .catch(err => console.log(err)); + */ Client.prototype.loginWithToken = function loginWithToken(token) { var email = arguments.length <= 1 || arguments[1] === undefined ? null : arguments[1]; @@ -81,7 +130,25 @@ var Client = (function (_EventEmitter) { return this.internal.loginWithToken(token, email, password).then(dataCallback(callback), errorCallback(callback)); }; - // def login + /** + * Log the client in using an email and password. + * @param {string} email Email of the Discord Account. + * @param {string} password Password of the Discord Account. + * @param {function(err: Error, token: string)} [callback] callback callback to the method + * @returns {Promise} Resolves with the token if the login was successful, otherwise it rejects with an error. + * @example + * // log the client in - callback + * client.login("jeff@gmail.com", "password", function(error, token){ + * if(!error){ + * console.log(token); + * } + * }); + * @example + * // log the client in - promise + * client.login("jeff@gmail.com", "password") + * .then(token => console.log(token)) + * .catch(err => console.log(err)); + */ Client.prototype.login = function login(email, password) { var callback = arguments.length <= 2 || arguments[2] === undefined ? function () /*err, token*/{} : arguments[2]; @@ -89,7 +156,25 @@ var Client = (function (_EventEmitter) { return this.internal.login(email, password).then(dataCallback(callback), errorCallback(callback)); }; - // def logout + /** + * Logs the client out gracefully and closes all WebSocket connections. Client still retains its Caches. + * @param {function(err: Error)} [callback] callback callback to the method + * @returns {Promise} Resolves with null if the logout was successful, otherwise it rejects with an error. + * @example + * // log the client out - callback + * client.logout(function(error){ + * if(error){ + * console.log("Couldn't log out."); + * }else{ + * console.log("Logged out!"); + * } + * }); + * @example + * // log the client out - promise + * client.logout() + * .then(() => console.log("Logged out!")) + * .catch(error => console.log("Couldn't log out.")); + */ Client.prototype.logout = function logout() { var callback = arguments.length <= 0 || arguments[0] === undefined ? function () /*err, {}*/{} : arguments[0]; @@ -97,7 +182,25 @@ var Client = (function (_EventEmitter) { return this.internal.logout().then(dataCallback(callback), errorCallback(callback)); }; - // def destroy + /** + * Similar to log out but this should be used if you know you aren't going to be creating the Client again later in your program. + * @param {function(err: Error)} [callback] callback callback to the method + * @returns {Promise} Resolves with null if the destruction was successful, otherwise it rejects with an error. + * @example + * // destroy the client - callback + * client.destroy(function(error){ + * if(error){ + * console.log("Couldn't destroy client."); + * }else{ + * console.log("Client destroyed!"); + * } + * }); + * @example + * // destroy the client - promise + * client.destroy() + * .then(() => console.log("Client destroyed!")) + * .catch(error => console.log("Couldn't destroy client.")); + */ Client.prototype.destroy = function destroy() { var _this = this; @@ -109,9 +212,36 @@ var Client = (function (_EventEmitter) { }).then(dataCallback(callback), errorCallback(callback)); }; - // def sendMessage + /** + * Sends a text message to the specified destination. + * @param {TextChannelResolvable} destination where the message should be sent + * @param {StringResolvable} content message you want to send + * @param {MessageOptions} [options] options you want to apply to the message + * @param {function(err: Error, msg: Message)} [callback] to the method + * @returns {Promise} Resolves with a Message if successful, otherwise rejects with an Error. + * @example + * // sending messages + * client.sendMessage(channel, "Hi there!"); + * client.sendMessage(user, "This is a PM message!"); + * client.sendMessage(server, "This message was sent to the #general channel of the server!"); + * client.sendMessage(channel, "This message is TTS.", {tts : true}); + * @example + * // callbacks + * client.sendMessage(channel, "Hi there!", function(err, msg){ + * if(err){ + * console.log("Couldn't send message"); + * }else{ + * console.log("Message sent!"); + * } + * }); + * @example + * // promises + * client.sendMessage(channel, "Hi there!") + * .then(msg => console.log("Message sent!")) + * .catch(err => console.log("Couldn't send message")); + */ - Client.prototype.sendMessage = function sendMessage(where, content) { + Client.prototype.sendMessage = function sendMessage(destination, content) { var options = arguments.length <= 2 || arguments[2] === undefined ? {} : arguments[2]; var callback = arguments.length <= 3 || arguments[3] === undefined ? function () /*err, msg*/{} : arguments[3]; @@ -121,20 +251,68 @@ var Client = (function (_EventEmitter) { options = {}; } - return this.internal.sendMessage(where, content, options).then(dataCallback(callback), errorCallback(callback)); + return this.internal.sendMessage(destination, content, options).then(dataCallback(callback), errorCallback(callback)); }; - // def sendTTSMessage + /** + * Sends a TTS text message to the specified destination. + * @param {TextChannelResolvable} destination where the message should be sent + * @param {StringResolvable} content message you want to send + * @param {function(err: Error, msg: Message)} [callback] to the method + * @returns {Promise} Resolves with a Message if successful, otherwise rejects with an Error. + * @example + * // sending messages + * client.sendTTSMessage(channel, "This message is TTS."); + * @example + * // callbacks + * client.sendTTSMessage(channel, "Hi there!", function(err, msg){ + * if(err){ + * console.log("Couldn't send message"); + * }else{ + * console.log("Message sent!"); + * } + * }); + * @example + * // promises + * client.sendTTSMessage(channel, "Hi there!") + * .then(msg => console.log("Message sent!")) + * .catch(err => console.log("Couldn't send message")); + */ - Client.prototype.sendTTSMessage = function sendTTSMessage(where, content) { + Client.prototype.sendTTSMessage = function sendTTSMessage(destination, content) { var callback = arguments.length <= 2 || arguments[2] === undefined ? function () /*err, msg*/{} : arguments[2]; - return this.sendMessage(where, content, { tts: true }).then(dataCallback(callback), errorCallback(callback)); + return this.sendMessage(destination, content, { tts: true }).then(dataCallback(callback), errorCallback(callback)); }; - // def reply + /** + * Replies to the author of a message in the same channel the message was sent. + * @param {MessageResolvable} message the message to reply to + * @param {StringResolvable} content message you want to send + * @param {MessageOptions} [options] options you want to apply to the message + * @param {function(err: Error, msg: Message)} [callback] to the method + * @returns {Promise} Resolves with a Message if successful, otherwise rejects with an Error. + * @example + * // reply to messages + * client.reply(message, "Hello there!"); + * client.reply(message, "Hello there, this is a TTS reply!", {tts:true}); + * @example + * // callbacks + * client.reply(message, "Hi there!", function(err, msg){ + * if(err){ + * console.log("Couldn't send message"); + * }else{ + * console.log("Message sent!"); + * } + * }); + * @example + * // promises + * client.reply(message, "Hi there!") + * .then(msg => console.log("Message sent!")) + * .catch(err => console.log("Couldn't send message")); + */ - Client.prototype.reply = function reply(where, content) { + Client.prototype.reply = function reply(message, content) { var options = arguments.length <= 2 || arguments[2] === undefined ? {} : arguments[2]; var callback = arguments.length <= 3 || arguments[3] === undefined ? function () /*err, msg*/{} : arguments[3]; @@ -144,7 +322,7 @@ var Client = (function (_EventEmitter) { options = {}; } - var msg = this.internal.resolver.resolveMessage(where); + var msg = this.internal.resolver.resolveMessage(message); if (msg) { if (!(msg.channel instanceof _StructuresPMChannel2["default"])) { content = msg.author + ", " + content; @@ -156,17 +334,62 @@ var Client = (function (_EventEmitter) { return Promise.reject(err); }; - // def replyTTS + /** + * Replies to the author of a message in the same channel the message was sent using TTS. + * @param {MessageResolvable} message the message to reply to + * @param {StringResolvable} content message you want to send + * @param {function(err: Error, msg: Message)} [callback] to the method + * @returns {Promise} Resolves with a Message if successful, otherwise rejects with an Error. + * @example + * // reply to messages + * client.replyTTS(message, "Hello there, this is a TTS reply!"); + * @example + * // callbacks + * client.replyTTS(message, "Hi there!", function(err, msg){ + * if(err){ + * console.log("Couldn't send message"); + * }else{ + * console.log("Message sent!"); + * } + * }); + * @example + * // promises + * client.replyTTS(message, "Hi there!") + * .then(msg => console.log("Message sent!")) + * .catch(err => console.log("Couldn't send message")); + */ - Client.prototype.replyTTS = function replyTTS(where, content) { + Client.prototype.replyTTS = function replyTTS(message, content) { var callback = arguments.length <= 2 || arguments[2] === undefined ? function () /*err, msg*/{} : arguments[2]; - return this.reply(where, content, { tts: true }).then(dataCallback(callback), errorCallback(callback)); + return this.reply(message, content, { tts: true }).then(dataCallback(callback), errorCallback(callback)); }; - // def deleteMessage + /** + * Deletes a message (if the client has permission to) + * @param {MessageResolvable} message the message to delete + * @param {MessageDeletionOptions} [options] options to apply when deleting the message + * @param {function(err: Error)} [callback] callback to the method + * @returns {Promise} Resolves with null if the deletion was successful, otherwise rejects with an Error. + * @example + * // deleting messages + * client.deleteMessage(message); + * client.deleteMessage(message, {wait:5000}); //deletes after 5 seconds + * @example + * // deleting messages - callback + * client.deleteMessage(message, function(err){ + * if(err){ + * console.log("couldn't delete"); + * } + * }); + * @example + * // deleting messages - promise + * client.deleteMessage(message) + * .then(() => console.log("deleted!")) + * .catch(err => console.log("couldn't delete")); + */ - Client.prototype.deleteMessage = function deleteMessage(msg) { + Client.prototype.deleteMessage = function deleteMessage(message) { var options = arguments.length <= 1 || arguments[1] === undefined ? {} : arguments[1]; var callback = arguments.length <= 2 || arguments[2] === undefined ? function () /*err, {}*/{} : arguments[2]; @@ -176,12 +399,34 @@ var Client = (function (_EventEmitter) { options = {}; } - return this.internal.deleteMessage(msg, options).then(dataCallback(callback), errorCallback(callback)); + return this.internal.deleteMessage(message, options).then(dataCallback(callback), errorCallback(callback)); }; - //def updateMessage + /** + * Edits a previously sent message (if the client has permission to) + * @param {MessageResolvable} message the message to edit + * @param {StringResolvable} content the new content of the message + * @param {MessageOptions} [options] options to apply to the message + * @param {function(err: Error, msg: Message)} [callback] callback to the method + * @returns {Promise} Resolves with the newly edited message if successful, otherwise rejects with an Error. + * @example + * // editing messages + * client.updateMessage(message, "This is an edit!"); + * @example + * // editing messages - callback + * client.updateMessage(message, "This is an edit!", function(err, msg){ + * if(err){ + * console.log("couldn't edit"); + * } + * }); + * @example + * // editing messages - promise + * client.updateMessage(message, "This is an edit!") + * .then(msg => console.log("edited!")) + * .catch(err => console.log("couldn't edit")); + */ - Client.prototype.updateMessage = function updateMessage(msg, content) { + Client.prototype.updateMessage = function updateMessage(message, content) { var options = arguments.length <= 2 || arguments[2] === undefined ? {} : arguments[2]; var callback = arguments.length <= 3 || arguments[3] === undefined ? function () /*err, msg*/{} : arguments[3]; @@ -191,10 +436,35 @@ var Client = (function (_EventEmitter) { options = {}; } - return this.internal.updateMessage(msg, content, options).then(dataCallback(callback), errorCallback(callback)); + return this.internal.updateMessage(message, content, options).then(dataCallback(callback), errorCallback(callback)); }; - // def getChannelLogs + /** + * Gets the logs of a channel with a specified limit, starting from the most recent message. + * @param {TextChannelResolvable} where the channel to get the logs of + * @param {Number} [limit=50] Integer, the maximum amount of messages to retrieve + * @param {ChannelLogsOptions} [options] options to use when getting the logs + * @param {function(err: Error, logs: Array)} [callback] callback to the method + * @returns {Promise, Error>} Resolves with an array of messages if successful, otherwise rejects with an error. + * @example + * // log content of last 500 messages in channel - callback + * client.getChannelLogs(channel, 500, function(err, logs){ + * if(!err){ + * for(var message of logs){ + * console.log(message.content); + * } + * } + * }); + * @example + * // log content of last 500 messages in channel - promise + * client.getChannelLogs(channel, 500) + * .then(logs => { + * for(var message of logs){ + * console.log(message.content); + * } + * }) + * .catch(err => console.log("couldn't fetch logs")); + */ Client.prototype.getChannelLogs = function getChannelLogs(where) { var limit = arguments.length <= 1 || arguments[1] === undefined ? 50 : arguments[1]; @@ -214,17 +484,59 @@ var Client = (function (_EventEmitter) { return this.internal.getChannelLogs(where, limit, options).then(dataCallback(callback), errorCallback(callback)); }; - // def getBans + /** + * Gets the banned users of a server (if the client has permission to) + * @param {ServerResolvable} server server to get banned users of + * @param {function(err: Error, bans: Array)} [callback] callback to the method + * @returns {Promise, Error>} Resolves with an array of users if the request was successful, otherwise rejects with an error. + * @example + * // loop through banned users - callback + * client.getBans(server, function(err, bans){ + * if(!err){ + * for(var user of bans){ + * console.log(user.username + " was banned from " + server.name); + * } + * } + * }); + * @example + * // loop through banned users - promise + * client.getBans(server) + * .then(bans => { + * for(var user of bans){ + * console.log(user.username + " was banned from " + server.name); + * } + * }) + * .catch(err => console.log("couldn't get bans")); + */ - Client.prototype.getBans = function getBans(where) { + Client.prototype.getBans = function getBans(server) { var callback = arguments.length <= 1 || arguments[1] === undefined ? function () /*err, bans*/{} : arguments[1]; - return this.internal.getBans(where).then(dataCallback(callback), errorCallback(callback)); + return this.internal.getBans(server).then(dataCallback(callback), errorCallback(callback)); }; - // def sendFile + /** + * Sends a file (embedded if possible) to the specified channel. + * @param {TextChannelResolvable} destination channel to send the file to + * @param {FileResolvable} attachment the file to send + * @param {string} name name of the file, especially including the extension + * @param {function(err: Error, msg: Message)} [callback] callback to the method + * @returns {Promise} resolves with the sent file as a message if successful, otherwise rejects with an error + * @example + * // send a file - callback + * client.sendFile(channel, new Buffer("Hello this a text file"), "file.txt", function(err, msg){ + * if(err){ + * console.log("Couldn't send file!"); + * } + * }); + * @example + * // send a file - promises + * client.sendFile(channel, "C:/path/to/file.txt", "file.txt") + * .then(msg => console.log("sent file!")) + * .catch(err => console.log("couldn't send file!")); + */ - Client.prototype.sendFile = function sendFile(where, attachment, name) { + Client.prototype.sendFile = function sendFile(destination, attachment, name) { var callback = arguments.length <= 3 || arguments[3] === undefined ? function () /*err, m*/{} : arguments[3]; if (typeof name === "function") { @@ -233,10 +545,27 @@ var Client = (function (_EventEmitter) { name = undefined; // Will get resolved into original filename in internal } - return this.internal.sendFile(where, attachment, name).then(dataCallback(callback), errorCallback(callback)); + return this.internal.sendFile(destination, attachment, name).then(dataCallback(callback), errorCallback(callback)); }; - // def joinServer + /** + * Client accepts the specified invite to join a server. If the Client is already in the server, the promise/callback resolve immediately. + * @param {InviteResolvable} invite invite to the server + * @param {function(err: Error, server: Server)} [callback] callback to the method. + * @returns {Promise} resolves with the newly joined server if succesful, reject with an error if not. + * @example + * // join a server - callback + * client.joinServer("https://discord.gg/0BwZcrFhUKZ55bJL", function(err, server){ + * if(!err){ + * console.log("Joined " + server.name); + * } + * }); + * @example + * // join a server - promises + * client.joinServer("https://discord.gg/0BwZcrFhUKZ55bJL") + * .then(server => console.log("Joined " + server.name)) + * .catch(err => console.log("Couldn't join!")); + */ Client.prototype.joinServer = function joinServer(invite) { var callback = arguments.length <= 1 || arguments[1] === undefined ? function () /*err, srv*/{} : arguments[1]; @@ -686,46 +1015,121 @@ var Client = (function (_EventEmitter) { get: function get() { return this.internal.users; } + + /** + * The server channels the Client is aware of. Only available after `ready` event has been emitted. + * @type {Cache} a Cache of the Server Channels + * @readonly + * @example + * // log the names of the channels and the server they belong to + * for(var channel of client.channels){ + * console.log(`${channel.name} is part of ${channel.server.name}`) + * } + */ }, { key: "channels", get: function get() { return this.internal.channels; } + + /** + * The servers the Client is aware of. Only available after `ready` event has been emitted. + * @type {Cache} a Cache of the Servers + * @readonly + * @example + * // log the names of the servers + * for(var server of client.servers){ + * console.log(server.name) + * } + */ }, { key: "servers", get: function get() { return this.internal.servers; } + + /** + * The PM/DM chats the Client is aware of. Only available after `ready` event has been emitted. + * @type {Cache} a Cache of the PM/DM Channels. + * @readonly + * @example + * // log the names of the users the client is participating in a PM with + * for(var pm of client.privateChannels){ + * console.log(`Participating in a DM with ${pm.recipient}`) + * } + */ }, { key: "privateChannels", get: function get() { return this.internal.private_channels; } + + /** + * The active voice connection of the Client, or null if not applicable. Only available after `ready` event has been emitted. + * @type {VoiceConnection|null} the voice connection (if any). + */ }, { key: "voiceConnection", get: function get() { return this.internal.voiceConnection; } + + /** + * Unix timestamp of when the Client first emitted the `ready `event. Only available after `ready` event has been emitted. + * @type {Number} timestamp of ready time + * @example + * // output when the client was ready + * console.log("I was first ready at " + client.readyTime); + */ }, { key: "readyTime", get: function get() { return this.internal.readyTime; } + + /** + * How long the client has been ready for in milliseconds. Only available after `ready` event has been emitted. + * @type {Number} number in milliseconds representing uptime of the client + * @example + * // log how long the client has been up for + * console.log("I have been online for " + client.uptime + " milliseconds"); + */ }, { key: "uptime", get: function get() { return this.internal.uptime; } + + /** + * A User object that represents the account the client is logged into. Only available after `ready` event has been emitted. + * @type {User} user representing logged in account of client. + * @example + * // log username of logged in account of client + * console.log("Logged in as " + client.user.username); + */ }, { key: "user", get: function get() { return this.internal.user; } + + /** + * Object containing user-agent information required for API requests. If not modified, it will use discord.js's defaults. + * @type {UserAgent} + * @example + * // log the stringified user-agent: + * console.log(client.userAgent.full); + */ }, { key: "userAgent", get: function get() { return this.internal.userAgent; }, + + /** + * Set the user-agent information provided. Follows the UserAgent typedef format excluding the `full` property. + * @type {UserAgent} + */ set: function set(userAgent) { this.internal.userAgent = userAgent; } diff --git a/lib/Client/Resolver/Resolver.js b/lib/Client/Resolver/Resolver.js index e154533d8..29d6756e1 100644 --- a/lib/Client/Resolver/Resolver.js +++ b/lib/Client/Resolver/Resolver.js @@ -1,6 +1,31 @@ "use strict"; /* global Buffer */ +/** + * Resolves supplied data type to a Channel. If a String, it should be a Channel ID. + * @typedef {(Channel|Server|Message|User|String)} ChannelResolvable +*/ +/** + * Resolves supplied data type to a TextChannel or PMChannel. If a String, it should be a Channel ID. + * @typedef {(TextChannel|PMChannel|Server|Message|User|String)} TextChannelResolvable +*/ +/** + * If given an array, turns it into a newline-separated string. + * @typedef {(String|Array)} StringResolvable +*/ +/** + * Resolves supplied data type to a Message. If a channel, it is the latest message from that channel. + * @typedef {(Message|TextChannel|PMChannel)} MessageResolvable +*/ +/** + * Resolves supplied data type to a Server. If a String, it should be the server's ID. + * @typedef {(Server|ServerChannel|Message|String)} ServerResolvable + */ +/** + * Resolves supplied data type to something that can be attached to a message. If a String, it can be an URL or a path to a local file. + * @typedef {(String|ReadableStream|Buffer)} FileResolvable + */ + exports.__esModule = true; function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; } diff --git a/lib/Structures/Message.js b/lib/Structures/Message.js index 27015ad87..153aa02b2 100644 --- a/lib/Structures/Message.js +++ b/lib/Structures/Message.js @@ -1,5 +1,11 @@ "use strict"; +/** + * Options that can be applied to a message before sending it. + * @typedef {(object)} MessageOptions + * @property {boolean} [tts=false] Whether or not the message should be sent as text-to-speech. +*/ + exports.__esModule = true; var _createClass = (function () { function defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } } return function (Constructor, protoProps, staticProps) { if (protoProps) defineProperties(Constructor.prototype, protoProps); if (staticProps) defineProperties(Constructor, staticProps); return Constructor; }; })(); diff --git a/lib/Util/TokenCacher-shim.js b/lib/Util/TokenCacher-shim.js index f483e9575..53412d365 100644 --- a/lib/Util/TokenCacher-shim.js +++ b/lib/Util/TokenCacher-shim.js @@ -6,23 +6,23 @@ exports.__esModule = true; function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } } var TokenCacher = (function () { - function TokenCacher() { - _classCallCheck(this, TokenCacher); - } + function TokenCacher() { + _classCallCheck(this, TokenCacher); + } - TokenCacher.prototype.setToken = function setToken() {}; + TokenCacher.prototype.setToken = function setToken() {}; - TokenCacher.prototype.save = function save() {}; + TokenCacher.prototype.save = function save() {}; - TokenCacher.prototype.getToken = function getToken() { - return null; - }; + TokenCacher.prototype.getToken = function getToken() { + return null; + }; - TokenCacher.prototype.init = function init(ind) { - this.done = true; - }; + TokenCacher.prototype.init = function init(ind) { + this.done = true; + }; - return TokenCacher; + return TokenCacher; })(); exports["default"] = TokenCacher; diff --git a/lib/Voice/VoicePacket.js b/lib/Voice/VoicePacket.js index 445f9d6c4..e62240c4c 100644 --- a/lib/Voice/VoicePacket.js +++ b/lib/Voice/VoicePacket.js @@ -5,24 +5,24 @@ exports.__esModule = true; function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } } var VoicePacket = function VoicePacket(data, sequence, time, ssrc) { - _classCallCheck(this, VoicePacket); + _classCallCheck(this, VoicePacket); - var audioBuffer = data, - returnBuffer = new Buffer(audioBuffer.length + 12); + var audioBuffer = data, + returnBuffer = new Buffer(audioBuffer.length + 12); - returnBuffer.fill(0); - returnBuffer[0] = 0x80; - returnBuffer[1] = 0x78; + returnBuffer.fill(0); + returnBuffer[0] = 0x80; + returnBuffer[1] = 0x78; - returnBuffer.writeUIntBE(sequence, 2, 2); - returnBuffer.writeUIntBE(time, 4, 4); - returnBuffer.writeUIntBE(ssrc, 8, 4); + returnBuffer.writeUIntBE(sequence, 2, 2); + returnBuffer.writeUIntBE(time, 4, 4); + returnBuffer.writeUIntBE(ssrc, 8, 4); - for (var i = 0; i < audioBuffer.length; i++) { - returnBuffer[i + 12] = audioBuffer[i]; - } + for (var i = 0; i < audioBuffer.length; i++) { + returnBuffer[i + 12] = audioBuffer[i]; + } - return returnBuffer; + return returnBuffer; }; exports["default"] = VoicePacket; diff --git a/lib/index.js b/lib/index.js index 010d2046c..ba2570dce 100644 --- a/lib/index.js +++ b/lib/index.js @@ -1,5 +1,35 @@ "use strict"; +/** + * Object containing user agent data required for API requests. + * @typedef {(object)} UserAgent + * @property {string} [url=https://github.com/hydrabolt/discord.js] URL to the repository/homepage of the creator. + * @property {string} [version=6.0.0] version of your bot. + * @property {string} full stringified user-agent that is generate automatically upon changes. Read-only. +*/ + +/** + * Object containing properties that can be used to alter the client's functionality. + * @typedef {(object)} ClientOptions + * @property {boolean} [compress=true] whether or not large packets that are sent over WebSockets should be compressed. + * @property {boolean} [revive=false] whether the Client should attempt to automatically reconnect if it is disconnected. + * @property {boolean} [rate_limit_as_error=false] whether rejections to API requests due to rate-limiting should be treated as errors. + * @property {Number} [large_threshold=250] an integer between 0 and 250. When a server has more users than `options.large_threshold`, only the online/active users are cached. +*/ + +/** + * Object containing properties that will be applied when deleting messages + * @typedef {(object)} MessageDeletionOptions + * @property {Number} [wait] If set, the message will be deleted after `options.wait` milliseconds. + */ + +/** + * Object containing properties that will be used when fetching channel logs. You cannot specify _both_ `options.before` and `options.after` + * @typedef {(object)} ChannelLogsOptions + * @property {MessageResolvable} [before] When fetching logs, it will fetch from messages before `options.before` but not including it. + * @property {MessageResolvable} [after] When fetching logs, it will fetch from messages after `options.after` but not including it. + */ + exports.__esModule = true; function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; } @@ -65,20 +95,20 @@ var _UtilCacheJs = require("./Util/Cache.js"); var _UtilCacheJs2 = _interopRequireDefault(_UtilCacheJs); exports["default"] = { - Client: _ClientClient2["default"], - Channel: _StructuresChannel2["default"], - ChannelPermissions: _StructuresChannelPermissions2["default"], - Invite: _StructuresInvite2["default"], - Message: _StructuresMessage2["default"], - PermissionOverwrite: _StructuresPermissionOverwrite2["default"], - PMChannel: _StructuresPMChannel2["default"], - Role: _StructuresRole2["default"], - Server: _StructuresServer2["default"], - ServerChannel: _StructuresServerChannel2["default"], - TextChannel: _StructuresTextChannel2["default"], - User: _StructuresUser2["default"], - VoiceChannel: _StructuresVoiceChannel2["default"], - Constants: _Constants2["default"], - Cache: _UtilCacheJs2["default"] + Client: _ClientClient2["default"], + Channel: _StructuresChannel2["default"], + ChannelPermissions: _StructuresChannelPermissions2["default"], + Invite: _StructuresInvite2["default"], + Message: _StructuresMessage2["default"], + PermissionOverwrite: _StructuresPermissionOverwrite2["default"], + PMChannel: _StructuresPMChannel2["default"], + Role: _StructuresRole2["default"], + Server: _StructuresServer2["default"], + ServerChannel: _StructuresServerChannel2["default"], + TextChannel: _StructuresTextChannel2["default"], + User: _StructuresUser2["default"], + VoiceChannel: _StructuresVoiceChannel2["default"], + Constants: _Constants2["default"], + Cache: _UtilCacheJs2["default"] }; module.exports = exports["default"]; diff --git a/src/Client/Client.js b/src/Client/Client.js index 6f4f42d5a..fbb3a008e 100644 --- a/src/Client/Client.js +++ b/src/Client/Client.js @@ -560,31 +560,90 @@ export default class Client extends EventEmitter { .then(dataCallback(callback), errorCallback(callback)); } - // def sendFile - sendFile(where, attachment, name, callback = (/*err, m*/) => { }) { + /** + * Sends a file (embedded if possible) to the specified channel. + * @param {TextChannelResolvable} destination channel to send the file to + * @param {FileResolvable} attachment the file to send + * @param {string} name name of the file, especially including the extension + * @param {function(err: Error, msg: Message)} [callback] callback to the method + * @returns {Promise} resolves with the sent file as a message if successful, otherwise rejects with an error + * @example + * // send a file - callback + * client.sendFile(channel, new Buffer("Hello this a text file"), "file.txt", function(err, msg){ + * if(err){ + * console.log("Couldn't send file!"); + * } + * }); + * @example + * // send a file - promises + * client.sendFile(channel, "C:/path/to/file.txt", "file.txt") + * .then(msg => console.log("sent file!")) + * .catch(err => console.log("couldn't send file!")); + */ + sendFile(destination, attachment, name, callback = (/*err, m*/) => { }) { if (typeof name === "function") { // name is the callback callback = name; name = undefined; // Will get resolved into original filename in internal } - return this.internal.sendFile(where, attachment, name) + return this.internal.sendFile(destination, attachment, name) .then(dataCallback(callback), errorCallback(callback)); } - // def joinServer + /** + * Client accepts the specified invite to join a server. If the Client is already in the server, the promise/callback resolve immediately. + * @param {InviteIDResolvable} invite invite to the server + * @param {function(err: Error, server: Server)} [callback] callback to the method. + * @returns {Promise} resolves with the newly joined server if succesful, rejects with an error if not. + * @example + * // join a server - callback + * client.joinServer("https://discord.gg/0BwZcrFhUKZ55bJL", function(err, server){ + * if(!err){ + * console.log("Joined " + server.name); + * } + * }); + * @example + * // join a server - promises + * client.joinServer("https://discord.gg/0BwZcrFhUKZ55bJL") + * .then(server => console.log("Joined " + server.name)) + * .catch(err => console.log("Couldn't join!")); + */ joinServer(invite, callback = (/*err, srv*/) => { }) { return this.internal.joinServer(invite) .then(dataCallback(callback), errorCallback(callback)); } - // def createServer + /** + * Creates a Discord Server and joins it + * @param {string} name the name of the server + * @param {region} [region=london] the region of the server + * @param {function(err: Error, server: Server)} [callback] callback to the method + * @returns {Promise} resolves with the newly created server if successful, rejects with an error if not. + * @example + * //creating a server - callback + * client.createServer("discord.js", "london", function(err, server){ + * if(err){ + * console.log("could not create server"); + * } + * }); + * @example + * //creating a server - promises + * client.createServer("discord.js", "london") + * .then(server => console.log("Made server!")) + * .catch(error => console.log("Couldn't make server!")); + */ createServer(name, region = "london", callback = (/*err, srv*/) => { }) { return this.internal.createServer(name, region) .then(dataCallback(callback), errorCallback(callback)); } - // def leaveServer + /** + * Leaves a Discord Server + * @param {ServerResolvable} server the server to leave + * @param {function(err: Error)} [callback] callback to the method + * @returns {Promise} resolves null if successful, otherwise rejects with an error. + */ leaveServer(server, callback = (/*err, {}*/) => { }) { return this.internal.leaveServer(server) .then(dataCallback(callback), errorCallback(callback)); @@ -602,7 +661,12 @@ export default class Client extends EventEmitter { .then(dataCallback(callback), errorCallback(callback)); } - // def deleteServer + /** + * Leaves a Discord Server, alias to `client.leaveServer` + * @param {ServerResolvable} server the server to leave + * @param {function(err: Error)} [callback] callback to the method + * @returns {Promise} resolves null if successful, otherwise rejects with an error. + */ deleteServer(server, callback = (/*err, {}*/) => { }) { return this.internal.leaveServer(server) .then(dataCallback(callback), errorCallback(callback)); diff --git a/src/Client/Resolver/Resolver.js b/src/Client/Resolver/Resolver.js index ec9cd6866..515791a56 100644 --- a/src/Client/Resolver/Resolver.js +++ b/src/Client/Resolver/Resolver.js @@ -17,6 +17,18 @@ * Resolves supplied data type to a Message. If a channel, it is the latest message from that channel. * @typedef {(Message|TextChannel|PMChannel)} MessageResolvable */ +/** + * Resolves supplied data type to a Server. If a String, it should be the server's ID. + * @typedef {(Server|ServerChannel|Message|String)} ServerResolvable + */ +/** + * Resolves supplied data type to something that can be attached to a message. If a String, it can be an URL or a path to a local file. + * @typedef {(String|ReadableStream|Buffer)} FileResolvable + */ +/** + * Resolves supplied data type to an invite ID. If a String, it should be an ID or a direct URL to the invite. + * @typedef {(Invite|String)} InviteIDResolvable + */ import fs from "fs"; import request from "superagent"; diff --git a/src/Structures/Server.js b/src/Structures/Server.js index 0084b1a56..442d85049 100644 --- a/src/Structures/Server.js +++ b/src/Structures/Server.js @@ -1,5 +1,10 @@ "use strict"; +/** + * Types of region for a server, include: `us-west`, `us-east`, `us-south`, `us-central`, `singapore`, `london`, `sydney`, `amsterdam` and `frankfurt` + * @typedef {(string)} region + */ + import Equality from "../Util/Equality"; import {Endpoints} from "../Constants"; import Cache from "../Util/Cache"; diff --git a/test/msgbot.js b/test/msgbot.js index 744614cc6..44a472655 100644 --- a/test/msgbot.js +++ b/test/msgbot.js @@ -64,9 +64,7 @@ client.on("message", msg => { if (msg.content.startsWith("$play")) { var url = msg.content.split(" ")[1]; - client.voiceConnection.playRawStream(request(url), { - volume : 0.1 - }); + client.voiceConnection.playRawStream(request(url)); }