From 79a8f6a9a5e7cbdf70960b1606b6d769edb3805e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20B=C3=B6gle?= Date: Thu, 14 Feb 2019 02:01:34 +0100 Subject: [PATCH 01/11] refactor/fix: split into seperate files, fix tsd generation --- .gitignore | 4 +- .npmignore | 14 +- .travis.yml | 5 +- README.md | 20 +- after_building.sed | 3 - api.js | 2716 -------------------------------------------- api/audio.js | 134 +++ api/backend.js | 197 ++++ api/db.js | 91 ++ api/engine.js | 232 ++++ api/event.js | 340 ++++++ api/format.js | 60 + api/fs.js | 118 ++ api/globals.js | 64 ++ api/graphics.js | 48 + api/helpers.js | 124 ++ api/http.js | 51 + api/media.js | 151 +++ api/net.js | 90 ++ api/store.js | 127 +++ api/types.js | 896 +++++++++++++++ api/ws.js | 66 ++ apply_favicon.sed | 3 + config.json | 4 +- documentation.yml | 49 +- generate.js | 33 - package.json | 4 +- 27 files changed, 2841 insertions(+), 2803 deletions(-) delete mode 100644 after_building.sed delete mode 100644 api.js create mode 100644 api/audio.js create mode 100644 api/backend.js create mode 100644 api/db.js create mode 100644 api/engine.js create mode 100644 api/event.js create mode 100644 api/format.js create mode 100644 api/fs.js create mode 100644 api/globals.js create mode 100644 api/graphics.js create mode 100644 api/helpers.js create mode 100644 api/http.js create mode 100644 api/media.js create mode 100644 api/net.js create mode 100644 api/store.js create mode 100644 api/types.js create mode 100644 api/ws.js create mode 100644 apply_favicon.sed delete mode 100644 generate.js diff --git a/.gitignore b/.gitignore index 830eb51..3e57c75 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,6 @@ # ignore built documentation files -documentation/ +documentation out node_modules package-lock.json -tsd/types.d.ts \ No newline at end of file +tsd \ No newline at end of file diff --git a/.npmignore b/.npmignore index 8639cc0..7c3eea8 100644 --- a/.npmignore +++ b/.npmignore @@ -1,2 +1,12 @@ -!tsd/types.d.ts -intellisense-demo.gif \ No newline at end of file +# keep tsd +!tsd + +# ignore other stuff +.git +.gitignore +.travis.yml +documentation/ +config.json +after_building.sed +intellisense-demo.gif +README.md diff --git a/.travis.yml b/.travis.yml index f64fe64..d2d7e79 100644 --- a/.travis.yml +++ b/.travis.yml @@ -3,12 +3,11 @@ node_js: - node script: - npm install -g documentation jsdoc -- documentation build api.js -c documentation.yml +- documentation build api/ -c documentation.yml --project-name "SinusBot Scripting Engine" --project-version " " --shallow -f html -o documentation -- sed -f after_building.sed -i documentation/index.html +- sed -f apply_favicon.sed -i documentation/index.html - jsdoc -c config.json || true -- node generate.js - cp tsd/types.d.ts documentation deploy: - provider: pages diff --git a/README.md b/README.md index 11779e6..9494401 100644 --- a/README.md +++ b/README.md @@ -19,13 +19,13 @@ npm install -g documentation ### Generate html file ```bash -documentation build api.js -c documentation.yml --project-name "SinusBot Scripting Engine" --project-version " " --shallow -f html -o documentation +documentation build api/ -c documentation.yml --project-name "SinusBot Scripting Engine" --project-version " " --shallow -f html -o documentation ``` ### Serve locally ```bash -documentation serve api.js -c documentation.yml --project-name "SinusBot Scripting Engine" --project-version " " --shallow -w +documentation serve api/ -c documentation.yml --project-name "SinusBot Scripting Engine" --project-version " " --shallow -w ``` ## IntelliSense @@ -38,27 +38,15 @@ There are TypeScript typings available which are generated out of the documentat First of all you need to install the typings by executing: `npm i sinusbot-scripting-engine` or `yarn add sinusbot-scripting-engine`. -After you have the typings installed, you need to create a `jsconfig.json` with the following content: +After you have the typings installed, you need to create a `jsconfig.json` in the folder where you develop your scripts with the following content: ```json { "compilerOptions": { - "target": "es5", + "target": "es5", // or "es6" if sinusbot version >1.0.0 "checkJs": true } } ``` -Or alternatively if you only want to enable type checking for specific files set the config to - -```json -{ - "compilerOptions": { - "target": "es5" - } -} -``` - -and add `// @ts-check` as the first line of your script that should be checked. - For reference, you can check out [this repository](https://github.com/SinusBot/scripts). diff --git a/after_building.sed b/after_building.sed deleted file mode 100644 index 8138531..0000000 --- a/after_building.sed +++ /dev/null @@ -1,3 +0,0 @@ -# insert the favicon meta tag and meta description before the head closing tag -/<\/head>/i\ - diff --git a/api.js b/api.js deleted file mode 100644 index d2a8636..0000000 --- a/api.js +++ /dev/null @@ -1,2716 +0,0 @@ -/** - * @description - * This is the first and only top-level function that should be called in your script, - * everything else will be done in the function that is passed to it. - * @example - * registerPlugin({ - * name: 'Demo Script', - * version: '1.0', - * description: 'This example actually does nothing', - * author: 'Author ', - * vars: [] - * }, function(_, config, meta) { - * // your code goes here - * }); - * @param {Manifest} manifest - * The manifest determines which features are available to the script and - * contains metadata and variables that will be shown in the web interface. - * @param {mainFunction} mainFunction - * If the script is activated this function is called when the scripts are loaded. - * The function receives three parameters, the first one (`_`) is deprecated and should **not** be used anymore. - */ -function registerPlugin(manifest, mainFunction) { } - -/** - * @class - * @mixin - * @see registerPlugin - * @param {string} name - Short name of your script - * @param {string} author - Your name and your email address in the form of: `your name ` - * @param {string} description - A longer description - tell the user what exactly your script does - * @param {string} version - Start with something like 1.0 and increase it with every release - * @param {boolean} [autorun] - Set to true, if you want the script to be run on every instance, without the option to disable it. - * @param {string[]} [backends] - * Per default scripts will only be available on TS3 instances. - * If your script supports Discord (or in the future maybe other backends) as well, you have to specify this explicitly by setting this variable to an array containing all backends: `backends: ["ts3", "discord"]` - * @param {boolean} [enableWeb] - * If your script required own web content, you can set enableWeb to true and put files into the ./scripts/scriptname/html directory. - * After restart, the script title will be clickable and lead to an index.html inside that html-directory you just created. - * - * From there you have access to the localStorage variables containing the login and may communicate with the bot api from your own pages. - * @param {string} [engine] - Sets the required engine version (bot version). This uses [Semantic Versioning](https://semver.org). Example: `engine: ">= 0.9.16"` - * @param {boolean} [hidden] - * Hides the script from the settings page. Should be used together with autorun. - * - * Hidden scripts can not have variables (vars), since they'd never be shown and thus not configurable. - * @param {string[]} [requiredModules] - * Using this, you can define which restricted modules the script wants to use. If it's not allowed via the config, the script will not load at all but instead return an error on startup. - * If you only optionally use features from restricted modules, don't use this but provide a fallback in your script. - * @param {object[]} [vars] - More information about the usage of variables can be found [here](https://wiki.sinusbot.com/en:guides:features:scripts:variables). - * @param {string[]} [voiceCommands] - * This parameter is only used for the speech recognition feature and may contain one or more strings that are to be detected for the given script. - * You can find more details on how to use it here: [Speech Recognition](https://wiki.sinusbot.com/en:guides:features:speechrecognition) - */ -class Manifest { } - -/** - * @callback mainFunction - * @see registerPlugin - * @param {object} [_] - This is **deprecated** and should **not** be used anymore. - * @param {object} config - Configuration of the plugin that the user set from within the web interface - * (given you have added anything to the vars field of your script manifest). - * @param {object} meta - Manifest as specified in registerPlugin. - */ -function mainFunction(_, config, meta) {} - -/** - * @class - * @mixin - * @example - * var engine = require('engine'); - * engine.log('Hello from a script!'); - */ -class Engine { - /** - * @returns {string} Current instances' unique identifier - */ - getInstanceID() { } - /** - * @returns {string} Current bots' unique identifier - */ - getBotID() { } - /** - * Returns the name of the used backend (e.g. "ts3" or "discord") - * @returns {string} Backend - */ - getBackend() { } - /** - * @description - * sets the log level of the instance - * ``` - * level | what gets logged - * ------|----------------- - * 0 | no log messages - * 1 | errors only - * 2 | errors and warnings - * 3 | errors, warnings, information - * 4 | ... - * 10 | most verbose - * 11 | most verbose + external backends - * ``` - * @param {number} level - Log level to set - * @returns {boolean} - * - */ - setInstanceLogLevel(level) { } - /** - * @description - * Sets the log level of the bot - * ``` - * level | what gets logged - * ------|----------------- - * 0 | no log messages - * 1 | errors only - * 2 | errors and warnings - * 3 | errors, warnings, information - * 4 | ... - * 10 | most verbose - * 11 | most verbose + external backends - * ``` - * @param {number} level - Log level to set - * @returns {boolean} - */ - setBotLogLevel(level) { } - /** - * Returns the log level of the instance - * @returns {number} The set loglevel - */ - getInstanceLogLevel() { } - /** - * Returns the log level of the bot - * @returns {number} The set loglevel - */ - getBotLogLevel() { } - /** - * Reloads all scripts; requires the corresponding setting in the config.ini to be enabled - * @returns {boolean} - */ - reloadScripts() { } - /** - * Returns the configured nickname - to get the actual nickname, use the backend module - * @returns {string} - */ - getNick() { } - /** - * Sets the nick to a new value and updates it on the server - * @param {string} nick - New nick - * @returns {boolean} - */ - setNick(nick) { } - /** - * Sets the default channel by its ID - * @param {string} channelID - * @returns {boolean} - */ - setDefaultChannelID(channelID) { } - /** - * Returns true if the backend of this instance has been started - * @returns {boolean} - */ - isRunning() { } - /** - * Sends a notification to all users that are currently using the webinterface; use this for startup errors - * @param {string} message - Message to send - */ - notify(message) { } - /** - * Stores the given object as configuration for the current script - * @param {object} config - * @returns {boolean} - */ - saveConfig() { } - /** - * Logs to stdout / instance log - * @param {any} log - */ - log(log) { } - /** - * Exports an object, so other Scripts are able to use functions or values of the Script - * @param {object} obj - object which should get exported - * @example - * // scriptname: exportscript.js - * var engine = require('engine'); - * var publicvariable = 'I get exportet!'; - * engine.export({ - * // returns the value of 'publicvariable' - * get: function get() { - * return publicvariable; - * }, - * // modifies the value of 'publicvariable' - * set: function get(value) { - * publicvariable = value; - * } - * }) - * @example - * var event = require('event'); - * var engine = require('engine'); - * event.on('load', function() { - * // must always be loaded AFTER the 'load' event - * var script = require('exportscript.js'); - * engine.log(script.get()); // logs 'I get exportet!' - * script.set('New Value'); - * engine.log(script.get()); // logs 'New Value' - * }); - */ - export(obj) { } - /** - * @description - * removes the current avatar image - * @returns {boolean} - */ - removeAvatar() { } - /** - * @description - * sets the avatar image to the album art of a given track - * @param {Track} track - Track to extract the album art from - * @returns {boolean} - */ - setAvatarFromTrack(track) { } - /** - * @description - * sets the avatar image to the manually uploaded image - * @returns {boolean} - */ - setDefaultAvatar() { } - /** - * @description - * sets the avatar to the rendered output of a banner template - * @param {string} bannerName - banner template to use - * @returns {boolean} - * @version 0.12.0 - */ - setAvatarFromBanner(bannerName) { } - /** - * @description - * sets the avatar to the given image as URL - * @param {string} url - image url - * @returns {boolean} - * @version 0.14.0 - */ - setAvatarFromURL(url) { } - /** - * @description Gets the users of the SinusBot - * @version 0.13.37 - * @returns {User[]} - */ - getUsers() { } - /** - * @description Gets a SinusBot user by his ID - * @version 0.13.37 - * @param {string} id - ID of the SinusBot user - * @returns {?User} - */ - getUserById(id) { } - /** - * @description Gets a Sinusbot user by his name. - * @version 0.13.37 - * @param {string} name - Name of the user - * @returns {?User} - */ - getUserByName(name) { } - /** - * @description Sets the command prefix. - * @version 0.14.0 - * @param {string} prefix - Command prefix - */ - setCommandPrefix(prefix) { } - /** - * @description Gets the command prefix. - * @version 0.14.0 - * @returns {string} Command prefix - */ - getCommandPrefix() { } -} - - -/** - * @class - * @mixin - * @example - * var store = require('store'); - * store.set('foo', 'bar'); - */ -class Store { - /** - * Stores a variable under the given key - * the values stored are only available for the current script, but shared between instances of it - * @param {string} key - * @param {any} value - Value to be stored; must be JSON.stringify()-able - * @returns {boolean} - * @example - * var store = require('store'); - * store.set('foo', 'bar'); - */ - set(key, value) { } - /** - * Gets a variable that has been stored previously by set() - * the values stored are only available for the current script, but shared between instances of it - * @param {string} key - * @returns {any} Stored value - or undefined, if not found - * @example - * var store = require('store'); - * var foo = store.get('foo'); - */ - get(key) { } - /** - * Deletes a stored variable by its key - * the values stored are only available for the current script, but shared between instances of it - * @param {string} key - */ - unset(key) { } - /** - * Returns an array of all set keys - * the values stored are only available for the current script, but shared between instances of it - * @returns {string[]} Array of all stored keys - */ - getKeys() { } - /** - * Returns all stored items - * the values stored are only available for the current script, but shared between instances of it - * @returns {object} Keys of this object are the keys of each entry - */ - getAll() { } - /** - * Stores a variable under the given key - * the values stored are available for every script of every instance - * @param {string} key - * @param {any} value - Value to be stored; must be JSON.stringify()-able - * @returns {boolean} - */ - setGlobal(key, value) { } - /** - * Gets a variable that has been stored previously by set() - * the values stored are available for every script of every instance - * @param {string} key - * @returns {any} Stored value - or undefined, if not found - */ - getGlobal(key) { } - /** - * Deletes a stored variable by its key - * the values stored are available for every script of every instance - * @param {string} key - */ - unsetGlobal(key) { } - /** - * Returns an array of all set keys - * the values stored are available for every script of every instance - * @returns {string[]} Array of all stored keys - */ - getKeysGlobal() { } - /** - * Returns all stored items - * the values stored are available for every script of every instance - * @returns {object} Keys of this object are the keys of each entry - */ - getAllGlobal() { } - /** - * Stores a variable under the given key - * the values stored are available only for the current instance of the script (not shared between instances and / or other scripts) - * @param {string} key - * @param {any} value - Value to be stored; must be JSON.stringify()-able - * @returns {boolean} - */ - setInstance(key, value) { } - /** - * Gets a variable that has been stored previously by set() - * the values stored are available only for the current instance of the script (not shared between instances and / or other scripts) - * @param {string} key - * @returns {any} Stored value - or undefined, if not found - */ - getInstance(key) { } - /** - * Deletes a stored variable by its key - * the values stored are available only for the current instance of the script (not shared between instances and / or other scripts) - * @param {string} key - */ - unsetInstance(key) { } - /** - * Returns an array of all set keys - * the values stored are available only for the current instance of the script (not shared between instances and / or other scripts) - * @returns {string[]} Array of all stored keys - */ - getKeysInstance() { } - /** - * Returns all stored items - * the values stored are available only for the current instance of the script (not shared between instances and / or other scripts) - * @returns {object} Keys of this object are the keys of each entry - */ - getAllInstance() { } -} - -/** - * @class - * @mixin - */ -class Backend { - /** - * @description Connects to the server - * @returns {boolean} - */ - connect() { } - /** - * @description Disconnects from the server - * @returns {boolean} - */ - disconnect() { } - /** - * Returns true if the backend is connected to a server - * @returns {boolean} - */ - isConnected() { } - /** - * @returns {string} Current bots' unique identifier - */ - getBotClientID() { } - /** - * @returns {Client} Client of the bot - */ - getBotClient() { } - /** - * Returns the actual nickname; To get the configured nickname, use engine.getNick() instead. - * @returns {string} - */ - getNick() { } - /** - * Returns a channel if found - * @param {string} id - * @returns {Channel} - * @example - * var backend = require('backend'); - * var channel = backend.getChannelByID('6'); - */ - getChannelByID(id) { } - /** - * Returns the (primary) channel the bot is in - * @returns {Channel} - * @example - * var backend = require('backend'); - * var channel = backend.getCurrentChannel(); - */ - getCurrentChannel() { } - /** - * Returns the matching channel if found - * @param {string} name - * @returns {Channel?} - * @see Backend#getChannelsByName() - * @example - * var backend = require('backend'); - * var channel = backend.getChannelByName('Welcome Channel'); - */ - getChannelByName(name) { } - /** - * Returns an array of channels matching the name - * @param {string} name - * @returns {Channel[]} - * @version 0.14.0 - * @example - * var backend = require('backend'); - * var channels = backend.getChannelsByName('foobar'); - */ - getChannelsByName(name) { } - /** - * Returns the total number of channels - * @returns {number} - * @example - * var backend = require('backend'); - * var count = backend.getChannelCount(); - */ - getChannelCount() { } - /** - * Returns all channels - * @returns {Channel[]} - * @example - * // Logs the name of all channels - * - * var backend = require('backend'); - * var engine = require('engine'); - * var channels = backend.getChannels(); - * - * channels.forEach(function(channel) { - * engine.log(channel.name()); - * }); - */ - getChannels() { } - /** - * Returns all clients - * @returns {Client[]} - * @example - * // Gets a list of all clients and sends them a message - * - * var backend = require('backend'); - * var clients = backend.getClients(); - * - * clients.forEach(function(client) { - * client.chat('Hello ', + client.name() + '. I\'m a SinusBot!'); - * }); - */ - getClients() { } - /** - * Returns a client by its temporary ID (changes when the client reconnects) - * @param {string} id - * @returns {Client} - */ - getClientByID(id) { } - /** - * Returns a client by its name/nickname - * @param {string} name - * @returns {Client} - */ - getClientByName(name) { } - /** - * Alias of getClientByName - * @param {string} name - * @returns {Client} - */ - getClientByNick(name) { } - /** - * Returns an (online) client by its permanent id - * @param {string} uniqueID - * @returns {Client} - */ - getClientByUniqueID(uniqueID) { } - /** - * Alias of getClientByUniqueID - * @param {string} uniqueID - * @returns {Client} - */ - getClientByUID(uniqueID) { } - /** - * @description Sends a message to the server - * @param {string} msg - Message to send - * @example - * var backend = require('backend'); - * backend.chat('Hello from SinusBot!'); - */ - chat(msg) { } - /** - * @description Creates a new channel - * @version 0.9.16.3 - * @param {ChannelParams} channelParams - * @returns {Channel} - Channel which was created - */ - createChannel(channelParams) { } - // TODO: change ID to Id; Support for both versions! - /** - * Returns a servergroup by its ID - * @param {string} id ServerGroup ID - * @returns {ServerGroup} - */ - getServerGroupByID(id) { } - // TODO: change ID to Id; Support for both versions! - /** - * Returns a channelgroup by its ID - * @param {string} id - ChannelGroup ID - * @returns {ChannelGroup} - */ - getChannelGroupByID(id) { } - /** - * Returns an array of all known server groups - * @returns {ServerGroup[]} - */ - getServerGroups() { } - /** - * Returns an array of all known channel groups - * @returns {ChannelGroup[]} - */ - getChannelGroups() { } -} - -/** - * @class - * @mixin - */ -class Media { - /** - * @description Plays a track via internal url - * @param {string} url - Internal url (like track://...) - * @returns {boolean} - */ - playURL(url) { } - /** - * Returns the current track - * @returns {Track} - */ - getCurrentTrack() { } - /** - * Returns the track with the given ID (or null if none was found) - * @returns {?Track} - */ - getTrackByID(id) { } - /** - * @description Searches for tracks matching the search term, returns 20 entries at most - * @param {string} searchString - * @returns {Track[]} - * @example - * var event = require('event'); - * var media = require('media'); - * - * event.on('chat', function(ev) { - * var params = ev.text.split(' '); - * if (params.length == 1) { - * ev.client.chat('Please enter a searchterm after .play - like .play november rain'); - * return; - * } - * if (params[0] == '.play') { - * params.shift(); - * var results = media.search(params.join(' ')); - * if (results.length > 0) { - * results[0].play(); - * ev.client.chat('Playing - just for you: ' + results[0].artist() + ' - ' + results[0].title()); - * } else { - * ev.client.chat('Sorry, I could not find anything that matched your search.'); - * } - * } - * }); - */ - search(searchString) { } - /** - * @description Adds the given url to the queue - * @param {string} url - * @returns {boolean} - */ - enqueue(url) { } - /** - * @description Adds the given url as the first entry in the queue - * @param {string} url - * @returns {boolean} - * @version 0.12.0 - */ - playAsNext(url) { } - /** - * @description Plays the next track of the queue / playlist - */ - playNext() { } - /** - * @description Plays the next previous of the queue / playlist - */ - playPrevious() { } - /** - * @description Stops playback completely - * @param {string} trackID - (optional) the track to stop; if not present, all tracks will be stopped - * @returns {boolean} - */ - stop(trackID) { } - /** - * Returns all tracks of the queue - * @returns {Track[]} - */ - getQueue() { } - /** - * Returns all playlists - * @returns {Playlist[]} - */ - getPlaylists() { } - /** - * Returns the playlists with the given id - * @returns {Playlist} - */ - getPlaylistByID(id) { } - /** - * Returns the currently active playlist - * @returns {Playlist} - */ - getActivePlaylist(id) { } - /** - * @description Removes the track at a given position from the queue - * @param {number} index - Index of the track that should be removed from the queue (0 being the first entry) - * @returns {boolean} - */ - removeFromQueue(index) { } - /** - * @description Removes all entries from the queue - * @returns {boolean} - */ - clearQueue() { } - /** - * @description Clears the current playlist (if set) so that playback won't continue inside that playlist - * @returns {boolean} - */ - clearPlaylist() { } - /** - * @description Streams a file via youtube-dl - * @param {string} url - Url that youtube-dl supports - */ - yt(url) { } - /** - * @description Downloads a file via youtube-dl, optionally plays it - * @param {string} url - Url that youtube-dl supports - * @param {boolean} play - Set to true to play after download - */ - ytdl(url, play) { } - /** - * @description Enqueues a stream via youtube-dl - * @param {string} url - Url that youtube-dl supports - */ - enqueueYt(url) { } - /** - * @description Downloads a file via youtube-dl, then enqueues it - * @param {string} url - Url that youtube-dl supports - */ - enqueueYtdl(url) { } -} - -/** - * @class - * @mixin - */ -class Audio { - /** - * @description Applies an audiofilter to the audio output - * @param {string} filter - ffmpeg compatible filter string - * @returns {boolean} - */ - setAudioFilter(filter) { } - /** - * @description Enables or disables audio return channel; required for speech recognition engine / recording - * @param {number} flags - bitmask; use 0x01 for general audio return (recording) or 0x02 for separated audio (for speech recognition) - 0x03 for both - * @returns {boolean} - * @version 0.13.37 - */ - setAudioReturnChannel(flags) { } - /** - * @description Starts recording to a file - * @returns {boolean} - */ - startRecording() { } - /** - * @description Stops recording to a file - * @returns {boolean} - */ - stopRecording() { } - /** - * @description Streams audio output to an icecast-server - * @param {string} url - Endpoint to stream to - * @param {string} username - Username used for authentication - * @param {string} password - Password - * @returns {boolean} - */ - streamToServer(url, username, password) { } - /** - * @description Stops streaming started with streamToServer - * @returns {boolean} - */ - stopStream() { } - /** - * Returns the state of repeat-mode - * @returns {boolean} - */ - isRepeat() { } - /** - * @description Sets the state of repeat-mode - * @param {boolean} val - */ - setRepeat(val) { } - /** - * Returns the state of shuffle-mode - * @returns {boolean} - */ - isShuffle() { } - /** - * @description Sets the state of shuffle-mode - * @param {boolean} val - */ - setShuffle(val) { } - /** - * Returns the current volume (0-100) - * @returns {number} volume - */ - getVolume() { } - /** - * @description Sets the volume (0-100) - * @param {number} volume - * @returns {boolean} - */ - setVolume(volume) { } - /** - * Returns the position of the current track - * @returns {number} position (in seconds) - */ - getTrackPosition() { } - /** - * @description Seeks to a specific position - * @param {number} pos - New position (in seconds) - */ - seek(pos) { } - /** - * Returns if the audio output has been muted - * @returns {boolean} - */ - isMute() { } - /** - * @description Enables/disables mute - * @param {boolean} mute - * @returns {boolean} - */ - setMute() { } - /** - * @returns {boolean} Whether the bot is playing music - */ - isPlaying() { } - /** - * @description Plays audio returned from the text-to-speech engine - * @param {string} text - Text to say - * @param {string} [locale] - Locale to use - */ - say(text, locale) { } - /** - * @description Returns the client count of the connected server - * @returns {number} client count - */ - getClientCount() { } - /** - * @description Sets the volume of a specific stream (0-100) - * @param {string} streamID - name or alias of the stream(s) to modify - * @param {number} volume - * @returns {boolean} - */ - setStreamVolume(streamID, volume) { } -} - -/** - * @class - * @mixin - */ -class Format { - /** - * @description Apply color if the backend supports it - * @param {string} text - Text that should be colored - * @param {string} color - Hex value of color to apply - * @returns {string} Formatted string - * @example - * // Sends a red-colored message to the server chat (requires permission to do so) - * var backend = require('backend'); - * var format = require('format'); - * backend.chat('This is SinusBot writing in ' + format.formatColor('red', '#aa0000')); - */ - color(text, color) { } - /** - * @description Apply italic formatting to text - * @param {string} text - * @returns {string} Formatted string - * @example - * // Sends a formattes message to the server chat (requires permission to do so) - * var backend = require('backend'); - * var format = require('format'); - * backend.chat('Part of this message is ' + format.italic('italic')); - */ - italic(text) { } - /** - * @description Apply bold formatting to text - * @param {string} text - * @returns {string} Formatted string - * @example - * // Sends a formattes message to the server chat (requires permission to do so) - * var backend = require('backend'); - * var format = require('format'); - * backend.chat('Part of this message is ' + format.bold('bold')); - */ - bold(text) { } - /** - * @description Apply underlined formatting to text - * @param {string} text - * @returns {string} Formatted string - * @example - * // Sends a formatted message to the server chat (requires permission to do so) - * var backend = require('backend'); - * var format = require('format'); - * backend.chat('Part of this message is ' + format.underline('underlined')); - */ - underline(text) { } - /** - * @description Formats text as code - * @param {string} text - * @returns {string} Formatted string - */ - code(text) { } -} - -/** - * @class - * @mixin - */ -class Helpers { - /** - * @description Returns a random numbers between zero and - * @param {number} max - * @returns {number} Random numbers - */ - getRandom(max) { } - /** - * @description Returns a random permutation of numbers between zero and - * @param {number} max - * @returns {number[]} A random permutation of numbers between zero and - */ - getRandPerm(max) { } - // TODO: Provide examples how this can be used - // /** - // * @description Creates a new BytesWriter - // * @version 1.0.0 - // * @returns {BytesWriter} - // */ - // newBytes() { } - /** - * @description Returns a BytesWriter for a given string - * @version 1.0.0 - * @param {string} value String - * @returns {BytesWriter} - */ - bytesFromString(value) { } - /** - * @description Returns a BytesWriter for a given hex-string - * @version 1.0.0 - * @param {string} value Hex-string - * @returns {BytesWriter} - */ - bytesFromHex(value) { } - /** - * @description Returns a BytesWriter for a given base64-string - * @version 1.0.0 - * @param {string} value Base64-string - * @returns {BytesWriter} - */ - bytesFromBase64(value) { } - /** - * @description Encodes a string to base64 - * @param {string} input - * @returns {string} - */ - base64Encode(input) { } - /** - * @description Decodes a string from base64 - * @param {string} input - * @returns {string} - */ - base64Decode(input) { } - /** - * @description Encodes a string to hex - * @param {string} input - * @returns {string} - */ - hexEncode(input) { } - /** - * @description Decodes a string from hex - * @param {string} input - * @returns {string} - */ - hexDecode(input) { } - /** - * @description Generate a hex-encoded MD5 checksum of the given input - * @param {string} input - * @returns {string} - */ - MD5Sum(input) { } - /** - * @description Generate a hex-encoded SHA1 checksum of the given input - * @param {string} input - * @returns {string} - */ - SHA1Sum(input) { } - /** - * @description Generate a hex-encoded SHA256 checksum of the given input - * @param {string} input - * @returns {string} - */ - SHA256Sum(input) { } - /** - * @description Gets the string representation of an object - * @deprecated This function should not be used anymore, if possible. - * @param input - * @returns {string} - */ - toString(input) { } - - // Semi-undocumented stuff: - // /** - // * @description Returns the documentation of a function - // * @deprecated Probably doesn't work anymore - // * @returns {string} JSDoc String - // */ - // document() { } - // /** - // * @description Returns the internal type of an object - // * @deprecated Shouldn't be used - // * @param input - // * @returns {string} Internal type - // */ - // typeOf(input) { } -} - -/** - * @class - * @mixin - * @fires api:eventName - * @fires discord:eventName - * @fires chat - * @fires poke - * @fires typing - * @fires track - * @fires trackInfo - * @fires trackEnd - * @fires ytdl.success - * @fires ytdl.error - * @fires connect - * @fires connectionFailed - * @fires disconnect - * @fires clientMove - * @fires clientNick - * @fires clientVisible - * @fires clientInvisible - * @fires clientKicked - * @fires clientKickedFromChannel - * @fires clientIPAddress - * @fires clientAway - * @fires clientBack - * @fires clientRecord - * @fires clientRecordStop - * @fires clientMute - * @fires clientUnmute - * @fires clientDeaf - * @fires clientUndeaf - * @fires serverGroupAdded - * @fires serverGroupRemoved - * @fires channelCreate - * @fires channelUpdate - * @fires channelDelete - * @fires speech - * @fires talkerCount - * @fires unload - * @fires load - * @example - * var event = require('event'); - * var engine = require('engine'); - * - * event.on('chat', function(ev) { - * engine.log('Got message "'+ev.text +'" from '+ ev.client.name()); - * }) - */ -class Event { - /** - * @description Registers an event listener - * @param {string} eventName - Event to listen to - * @param {function} callback - Gets called when the given event is triggered - */ - on(eventName, callback) { } - /** - * @description Emits an event to the current instance - * @param {string} eventName - Name of the event to be emitted - * @param {object} data - A data object to be sent with the event - */ - emit(eventName, data) { } - /** - * @description Emits an event to all instances - * @param {string} eventName - Name of the event to be emitted - * @param {object} data - A data object to be sent with the event - */ - broadcast(eventName, data) { } -} - -/** - * @class - * @mixin - * @description This type is passed to the `api:$eventName`-event, see {@link Event.api:eventName} for more. - */ -class APIEvent { - /** - * @returns {string} Name of the event - */ - name() { } - /** - * @returns {object} Json body - */ - data() { } - /** - * @returns {User} User that called the event (or null, if unset) - */ - user() { } - /** - * @returns {string} Remote address that triggered the call - */ - remoteAddr() { } - /** - * @version 0.14 - * @returns {object} Key/Value map of the query parameters in the url - */ - queryParams() { } -} - -/** - * @event api:$eventName - * @memberof Event - * @param {APIEvent} - * @description Gets fired whenever api:$eventName is triggered by via the web api - */ -/** - * @event chat - * @memberof Event - * @param {Message} msg - Message - * @description - * This event gets triggered whenever a chat message has been received. - * This also counts for messages from the bot itself, so make sure to check. - * @example - * var event = require('event'); - * var engine = require('engine'); - * - * event.on('chat', function(ev) { - * engine.log('Got message "'+ev.text +'" from '+ ev.client.name()); - * }); - */ -/** - * @event poke - * @memberof Event - * @param {Message} msg - Message - * @description Gets fired whenever the bot is poked - * @example - * var event = require('event'); - * var engine = require('engine'); - * - * event.on('poke', function(ev) { - * engine.log('Got poke message "'+ev.text +'" from '+ ev.client.name()); - * }); - */ -/** - * @event typing - * @memberof Event - * @param {Client} client - Client that started typing - * @description Gets fired whenever a client starts typing in a chat with the bot - */ -/** - * @event track - * @memberof Event - * @param {Track} track - * @description Gets fired whenever a new track starts - */ -/** - * @event trackInfo - * @memberof Event - * @param {Track} track - * @description Gets fired whenever a track changes its information (like radio stations) - */ -/** - * @event trackEnd - * @memberof Event - * @param {Track} track - * @param {string} callback - Callback string - * @description Gets fired whenever a track has stopped playing - */ -/** - * @event ytdl.success - * @memberof Event - * @param {string} url - * @param {string} jobId - * @param {string} trackId - * @description Gets fired whenever a track was successfully downloaded via ytdl - */ -/** - * @event ytdl.error - * @memberof Event - * @param {string} url - * @param {string} jobId - * @param {string} trackId - * @description Gets fired whenever a download via ytdl fails - */ -/** - * @event connect - * @memberof Event - * @description Gets fired whenever a connection with the server has been established - */ -/** - * @event connectionFailed - * @memberof Event - * @param {string} reason - * @description Gets fired whenever the client is unable to connect to a server - */ -/** - * @event disconnect - * @memberof Event - * @description Gets fired whenever the bots connection to the server is closed - */ -/** - * @event clientMove - * @memberof Event - * @param {MoveInfo} moveInfo - * @description Gets fired whenever a client moves, joins or disconnects - */ -/** - * @event clientNick - * @memberof Event - * @param {Client} client - * @param {string} oldNick - * @description Gets fired whenever a clients nickname is changed - */ -/** - * @event clientVisible - * @memberof Event - * @param {MoveInfo} moveInfo - * @description Gets fired whenever a client becomes visible to the bot - */ -/** - * @event clientInvisible - * @memberof Event - * @param {MoveInfo} moveInfo - * @description Gets fired whenever a client becomes invisible to the bot - */ -/** - * @event clientKicked - * @memberof Event - * @param {MoveInfo} moveInfo - * @description Gets fired whenever a client gets kicked from the server - */ -/** - * @event clientKickedFromChannel - * @memberof Event - * @param {MoveInfo} moveInfo - * @description Gets fired whenever a client gets kicked from a channel - */ -/** - * @event clientIPAddress - * @memberof Event - * @param {Client} client - * @description Gets fired whenever a clients IP address changes or has initially been fetched - */ -/** - * @event clientAway - * @memberof Event - * @param {Client} client - * @description Gets fired whenever a client sets himself as away - */ -/** - * @event clientBack - * @memberof Event - * @param {Client} client - * @description Gets fired whenever a client removes himself as away - */ -/** - * @event clientRecord - * @memberof Event - * @param {Client} client - * @description Gets fired whenever a client starts recording - */ -/** - * @event clientRecordStop - * @memberof Event - * @param {Client} client - * @description Gets fired whenever a client stops recording - */ -/** - * @event clientMute - * @memberof Event - * @param {Client} client - * @description Gets fired whenever a client mutes his microphone - */ -/** - * @event clientUnmute - * @memberof Event - * @param {Client} client - * @description Gets fired whenever a client unmutes his microphone - */ -/** - * @event clientDeaf - * @memberof Event - * @version 0.9.18 - * @param {Client} client - * @description Gets fired whenever a client mutes his sound - */ -/** - * @event clientUndeaf - * @memberof Event - * @version 0.9.18 - * @param {Client} client - * @description Gets fired whenever a client unmutes his sound - */ -/** - * @event serverGroupAdded - * @memberof Event - * @param {ClientServerGroupEvent} event - * @description Gets fired whenever a client got added to a server group - */ -/** - * @event serverGroupRemoved - * @memberof Event - * @param {ClientServerGroupEvent} event - * @description Gets fired whenever a client got removed from a server group - */ -/** - * @event channelCreate - * @memberof Event - * @param {Channel} channel - Channel that got created - * @param {Client} invoker - Client that created the channel - * @description Gets fired whenever a channel is created - */ -/** - * @event channelUpdate - * @memberof Event - * @param {Channel} channel - Channel that got updated - * @param {Client} invoker - Client that updated the channel - * @description Gets fired whenever a channel is updated - */ -/** - * @event channelDelete - * @memberof Event - * @param {Channel} channel - Channel that got deleted - * @param {Client} invoker - Client that deleted the channel - * @description Gets fired whenever a channel is deleted - */ -/** - * @event speech - * @memberof Event - * @param {object} ev - Event data - * @param {Client} ev.client - Client - * @param {string} ev.text - Recognized text - * @version 0.13.37 - * @description - * This event gets triggered whenever the bot recognizes a voice command that the script registered, assuming: - * 1) SpeechRecognition was installed - * 2) SpeechRecognition is enabled in the config.ini - * 3) The voice command was registered by the script in registerPlugin - * 4) AudioReturnChannel is set to 2 - * - * Check out [the wiki article](https://wiki.sinusbot.com/en:guides:features:speechrecognition) for more the complete list of reqirements and instructions on how to install it. - * @example - * var event = require('event'); - * var engine = require('engine'); - * var audio = require('audio'); - * - * audio.setAudioReturnChannel(2) - * - * event.on('speech', function(ev) { - * engine.log('Got speech command "' + ev.text + '" from ' + ev.client.name()); - * }); - */ -/** - * @event talkerCount - * @memberof Event - * @param {number} number - Number of users that are currently talking in the channel - * @description Gets fired whenever the number of users that are currently talking in the channel changes - */ -/** - * @event unload - * @memberof Event - * @description Gets fired whenever the script is going to be unloaded or reloaded; use this to clean up or save stuff - */ -/** - * @event load - * @memberof Event - * @description Gets fired when all scripts have been loaded - */ -/** - * @event discord:$eventName - * @memberof Event - * @param {object} ev - Discord event data - * @description - * This event gets triggered whenever a discord event got received. - * Every event will be emitted in uppercase and the spaces will be replaced by underscores. - * All available discord events are documentated here: https://discordapp.com/developers/docs/topics/gateway#events - * @example - * var event = require('event'); - * var engine = require('engine'); - * - * event.on('discord:GUILD_CREATE', function (ev) { - * engine.log('GUILD_CREATE' + JSON.stringify(ev)); - * }); - */ -/** - * @event ws.connect - * @memberof Event - * @version 0.9.20 - * @see WS - * @param {string} id - ID of the new connection - */ -/** - * @event ws.close - * @memberof Event - * @version 0.9.20 - * @see WS - * @param {string} id - ID of the closed connection - */ -/** - * @event ws.error - * @memberof Event - * @version 0.9.20 - * @see WS - * @param {string} id - ID of the connection - * @param {string} error - Error - */ -/** - * @event ws.data - * @memberof Event - * @version 0.9.20 - * @see WS - * @param {string} id - ID of the connection - * @param {number} type - Type of the message - * @param {Bytes} data - Data object - */ - -/** - * @class - * @mixin - * @property {string} text - Text of the message - * @property {Channel} channel - Channel (if given) this message has been sent on - * @property {Client} client - Client that sent the message - * @property {number} mode - Number representing the way this message has been sent - * (1 = private, 2 = channel, 3 = server) - */ -class Message { } - -/** - * @class - * @mixin - * @property {?Channel} fromChannel - Old channel (or null if the client just got online / changed visibility) - * @property {?Channel} toChannel - New channel (or null if the client just went offline / changed visibility) - * @property {Client} client - Client that was moved - * @property {Client} invoker - Client that invoked the move - */ -class MoveInfo { } - -/** - * @class - * @mixin - * @description Note: if the client is inivisible to the bot, some fields might not be available. - */ -class Client { - /** - * @returns {string} Name/nickname of the client - */ - name() { } - /** - * Alias of name() - * @returns {string} Name/nickname of the client - */ - nick() { } - /** - * @returns {string} Phonetic name of the client; useful for tts - */ - phoneticName() { } - /** - * @returns {string} Temporary ID of the client - */ - id() { } - /** - * Alias of uniqueId() - * @returns {string} Unique ID of the client - */ - uid() { } - /** - * @returns {string} Unique ID of the client - */ - uniqueId() { } - // TODO: change ID to Id; Support for both versions! - /** - * @returns {string} TeamSpeak database ID of the client - */ - databaseID() { } - /** - * @returns {string} Country of the client - */ - country() { } - /** - * @returns {string} Description of the client - */ - description() { } - /** - * @param {string} description - * @version 0.9.19 - */ - setDescription(description) { } - /** - * @returns {number} Number of times the client has connected - */ - getTotalConnectionsCount() { } - /** - * Returns true when this client is the bot itself - * @returns {boolean} - */ - isSelf() { } - /** - * Returns if the client is recording the conversation - * @returns {string} - */ - isRecording() { } - /** - * Returns if the client is muted (has its microphone disabled) - * @returns {boolean} - */ - isMuted() { } - /** - * Returns if the client is deaf (has its loudspeakers disabled) - * @returns {boolean} - */ - isDeaf() { } - /** - * Returns if the client is away - * @returns {boolean} - */ - isAway() { } - /** - * Returns the clients' servergroups - * @returns {ServerGroup[]} - */ - getServerGroups() { } - /** - * Returns the clients' channelgroup - * @returns {ChannelGroup} - */ - getChannelGroup() { } - /** - * Returns the clients' away message (if set) - * @returns {string} - */ - getAwayMessage() { } - /** - * Returns the clients' last ping time (latency) - * @returns {number} - */ - getPing() { } - /** - * Returns the clients' ip address (if available) - * @returns {string} - */ - getIPAddress() { } - /** - * Returns the clients' online time (requires special permissions) - * @returns {number} in milliseconds - */ - getOnlineTime() { } - /** - * Returns the clients' current idle time (requires special permissions) - * @returns {number} in milliseconds - */ - getIdleTime() { } - /** - * Returns the clients' packet loss percentage (requires special permissions) - * @returns {number} - */ - getPacketLoss() { } - /** - * Returns the clients' amount of received data (requires special permissions) - * @returns {number} - */ - getBytesReceived() { } - /** - * Returns the clients' amount of sent data (requires special permissions) - * @returns {number} - */ - getBytesSent() { } - /** - * Returns the total number of connections from that client - * On TS3, this information has to be actively requested from the server. If the bot is unable to get it or hasn't received an answer in time, it will return <= 0 here. - * @returns {number} - */ - getTotalConnections() { } - /** - * Returns the time the client has been created / was first seen by the server - * On TS3, this information has to be actively requested from the server. If the bot is unable to get it or hasn't received an answer in time, it will return <= 0 here. - * @returns {number} - */ - getCreationTime() { } - /** - * Returns an array of all channels the client is in; even if TS only uses one channel for a client at a time, other backends might provide several - * @returns {Channel[]} Array of channels - */ - getChannels() { } - /** - * @returns {Channel} Current audio channel the client is in - */ - getAudioChannel() { } - /** - * Returns the TS3 client URL in the format `client://0/uid~nickname` - * @returns {string} Client URL - */ - getURL() { } - /** - * @description Compares two clients - * @param {Client} otherClient - * @returns {boolean} true, if both clients are the same - */ - equals(otherClient) { } - /** - * @description Sends a message to the client - * @param {string} msg - Message to send - * @example - * var backend = require('backend'); - * var client = backend.getClientByName('Bob'); - * client.chat('Hello, ' + client.name()); - */ - chat(msg) { } - /** - * @description Pokes the client with a message - * @param {string} msg - Message to send - * @example - * var backend = require('backend'); - * var client = backend.getClientByName('Bob'); - * client.chat('Pokeypoke, ' + client.name() + '!'); - */ - poke(msg) { } - /** - * @description Bans a client - * @param {number} time - Amount of time the ban should last - * @param {string} msg - Message to send - * @example - * var backend = require('backend'); - * var client = backend.getClientByName('Bob'); - * client.ban(100, 'See you in 100 seconds, ' + client.name() + '!'); - */ - ban(time, msg) { } - /** - * @description Kicks the client from the server - * @param {string} msg - Message to send - */ - kick(msg) { } - /** - * @description Kicks the client from the server - * @param {string} msg - Message to send - */ - kickFromServer(msg) { } - /** - * @description Kicks the client from the channel - * @param {string} msg - Message to send - */ - kickFromChannel(msg) { } - /** - * @description Adds a client to a specific ServerGroup - * @param {(ServerGroup|string|number)} group - Servergroup the client should be added to - */ - addToServerGroup(group) { } - /** - * @description Removes a client from a specific ServerGroup - * @param {(ServerGroup|string|number)} group - Servergroup the client should be removed from - */ - removeFromServerGroup(id) { } - /** - * @description - * Moves a client to another channel - * - * *Note: This can also be used to disconnect a discord bot-instance from the voice chat with `backend.getBotClient().moveTo('')`. - * @param {Channel} target - Channel the client should be moved to - * @param {string} [password] - Password for the target channel, if required - */ - moveTo(target, password) { } - /** - * @description Enables / disables subscription for this client; requires subscription mode - * @param {boolean} val - */ - setSubscription(val) { } - /** - * @description Returns the platform of the client (Windows, Linux, MacOS) - * @returns {string} platform - */ - getPlatform() { } - /** - * @description Returns the version of the client - * @returns {string} version - */ - getVersion() { } - /** - * @description Returns the client type (Query=0; Normal=1) - * @returns {string} client type - */ - type() { } -} - -/** - * @class - * @mixin - * @property {client} client - Client that has been added / removed - * @property {client} invoker - Client that added client to the group - * @property {serverGroup} serverGroup - Server Group - */ -class ClientServergroupEvent { } - -/** - * @class - * @mixin - */ -class Channel { - /** - * @returns {string} ID - */ - id() { } - /** - * @returns {string} Name - */ - name() { } - /** - * @returns {?Channel} Parent of channel or null if none is set - */ - parent() { } - /** - * @version 0.9.16.3 - * @returns {number} Order / position of this channel. - * For ts3 this is a numeric value determining the order in which channels are displayed below their parent. To set a new value, please use moveTo. - */ - position() { } - /** - * @description delete the current channel - * @version 0.9.17 - * @returns {boolean} - */ - delete() { } - /** - * @description Moves the channel to a new parent with a new position value - * @version 0.9.16.3 - * @param {(string|Channel)} parent - New parent channel - * @param {number} order - New order value - */ - moveTo(parent, order) { } - /** - * @param {string} name - * @version 0.9.16 - */ - setName(name) { } - /** - * @returns {number} Type (0 = voice, 1 = text) - */ - type() { } - /** - * @returns {string} Topic - */ - topic() { } - /** - * @param {string} topic - * @version 0.9.16 - */ - setTopic(topic) { } - /** - * @version 0.9.19 - * @returns {string} Description - */ - description() { } - /** - * @param {string} description - * @version 0.9.16 - */ - setDescription(description) { } - /** - * @returns {number} Codec - */ - codec() { } - /** - * @param {number} codec - * @version 0.9.16 - */ - setCodec(codec) { } - /** - * @returns {number} Codec quality - */ - codecQuality() { } - /** - * @param {number} quality - * @version 0.9.16 - */ - setCodecQuality(quality) { } - /** - * @returns {number} Configured number of clients the channel can hold (-1 if unlimited) - */ - maxClients() { } - /** - * @param {boolean} maxClients Set to -1 for unlimited clients - * @version 0.9.16 - */ - setMaxClients(maxClients) { } - /** - * @returns {number} - */ - maxFamilyClients() { } - /** - * @param {boolean} maxFamilyClients - * @version 0.9.16 - */ - setMaxFamilyClients(maxFamilyClients) { } - /** - * @returns {boolean} Whether channel is permanent or not - */ - isPermanent() { } - /** - * @param {boolean} permanent - * @version 0.9.16 - */ - setPermanent(permanent) { } - /** - * @returns {boolean} Whether channel is semi-permanent or not - */ - isSemiPermanent() { } - /** - * @param {boolean} permanent - * @version 0.9.16 - */ - setSemiPermanent(permanent) { } - /** - * @returns {boolean} Whether channel is the default one - */ - isDefault() { } - /** - * @returns {boolean} Whether channel is password-protected or not - */ - isPassworded() { } - /** - * @returns {boolean} Whether channel is encrypted or not - */ - isEncrypted() { } - /** - * @param {boolean} encrypted - * @version 0.9.16 - */ - setEncrypted(encrypted) { } - /** - * @description Compares two channels - * @param {Channel} otherChannel - * @returns {boolean} True, if both channels are the same - */ - equals(otherChannel) { } - /** - * @description Sends a chat message to the channel - * @param {string} msg - Message to send - */ - chat(msg) { } - /** - * @returns {Client[]} Clients that are in this channel - */ - getClients() { } - /** - * @returns {number} Number of clients that are in the channel - */ - getClientCount() { } - /** - * @description enables / disables subscription for this channel; requires subscription mode - * @param {boolean} val - */ - setSubscription(val) { } - /** - * @description Updates multiple channel parameters at once - * @version 0.9.16.3 - * @param {ChannelParams} channelParams - */ - update(channelParams) { } - /** - * @description Assigns a client to a channel group - * @version 0.9.18 - * @param {Client} client - * @param {ChannelGroup} channelGroup - */ - setChannelGroup(client, channelGroup) { } - /** - * @description Gets the permissions for the channel from the server - this is an expensive call as the permissions are _not_ cached - * @version 0.13.37 - * @returns {Permission[]} - */ - getPermissions() { } - /** - * @description Adds/sets a new permission on the channel; you need to use the setters and then call save() to apply - can also be used to remove a permission by delete() afterwards - * @version 0.13.37 - * @param {string} id - id of the permission to add; can also be supplied as name like i_channel_needed_join_power - * @returns {Permission} - */ - addPermission(id) { } -} - -/** - * @class - * @mixin - * @property {string} name - Displayname of the channel; mandatory on create - * @property {(Channel|number|string)} parent - Parent channel (you can also use the channelId); ignored on update, mandatory on create - * @property {string} description - * @property {string} topic - * @property {string} password - * @property {number} codec - See codec types for explanation - * @property {number} codecQuality - * @property {boolean} encrypted - True by default - * @property {boolean} permanent - * @property {boolean} semiPermanent - * @property {number} position - * @property {number} maxClients - Set to -1 for unlimited clients - * @property {number} maxFamilyClients - * @property {boolean} default - Whether the channel is the default channel - * @property {number} neededTalkPower - TS only; 0.9.19+ - * @property {number} deleteDelay - TS only; 0.9.19+ - * @property {number} icon - TS only; 0.9.19+ - * @description - * Used to update or create a channel; - * When creating a channel parent and name are mandatory for TS3; - * When updating a channel parent will be ignored (use moveTo instead) - */ -class ChannelParams { } - -/** - * @class - * @mixin - */ -class ServerGroup { - /** - * @returns {string} ID of the server group - */ - id() { } - /** - * @returns {string} Name of the server group - */ - name() { } - /** - * @returns {string} ID of the icon used for the channel group - * @version 0.12.0 - */ - icon() { } - /** - * @description Adds a client by database ID to the servergroup - * @returns {boolean} status if the request was successful - * @version 0.13.37 - * @param {(Client|string|number)} client - The client can be a client object, string or number - */ - addClientByDatabaseId(client) { } - /** - * @description Gets the permissions for the servergroup from the server - this is an expensive call as the permissions are _not_ cached - * @version 0.13.37 - * @returns {Permission[]} - */ - getPermissions() { } - /** - * @description Adds/sets a new permission to the servergroup; you need to use the setters and then call save() to apply - can also be used to remove a permission by delete() afterwards - * @version 0.13.37 - * @param {string} id - id of the permission to add; can also be supplied as name like i_channel_needed_join_power - * @returns {Permission} - */ - addPermission(id) { } -} - -/** - * @class - * @mixin - */ -class ChannelGroup { - /** - * @returns {string} ID of the channel group - */ - id() { } - /** - * @returns {string} Name of the channel group - */ - name() { } - /** - * @returns {string} ID of the icon used for the channel group - * @version 0.12.0 - */ - icon() { } - /** - * @description Gets the permissions for the channelgroup from the server - this is an expensive call as the permissions are _not_ cached - * @version 0.13.37 - * @returns {Permission[]} - */ - getPermissions() { } - /** - * @description Adds/sets a new permission to the channelgroup; you need to use the setters and then call save() to apply - can also be used to remove a permission by delete() afterwards - * @version 0.13.37 - * @param {string} id - id of the permission to add; can also be supplied as name like i_channel_needed_join_power - * @returns {Permission} - */ - addPermission(id) { } -} - -/** - * @class - * @mixin - */ -class User { - /** - * @description Returns the ID of the user - * @returns {string} ID of the User - * @version 0.13.37 - */ - id() { } - /** - * @description Returns the name of the user - * @returns {string} Name of the User - * @version 0.13.37 - */ - name() { } - /** - * @description Returns the privileges of the user - * @returns {number} Privileges of the user - * @version 0.13.37 - */ - privileges() { } - /** - * @description Returns the teamspeak unique ID of the bind client - * @returns {string} teamspeak unique ID of the bind ts client - * @version 0.13.37 - */ - tsUid() { } - /** - * @description Returns the teamspeak group ID - * @returns {string} ID of the bind teamspeak group - * @version 0.13.37 - */ - tsGroupId() { } - /** - * @description Checks if an user is an admin - * @returns {boolean} Admin status of the user - * @version 0.13.37 - */ - isAdmin() { } - /** - * @description Sets a new password to the user - * @returns {boolean} Success or not - * @param {string} password - new password of the user - * @version 0.13.37 - */ - setPassword(password) { } - /** - * @description Sets the teamspeak unique ID to the user - * @returns {boolean} Success or not - * @param {string} tsUid - teamspeak unique ID of the client - * @version 0.13.37 - */ - setTSUid(tsUid) { } - /** - * @description Sets the privileges to an user - * @returns {boolean} Success or not - * @param {number} privileges - New privileges of the user - * @version 0.13.37 - */ - setPrivileges(privileges) { } - /** - * @description Adds an privilege to an user - * @returns {boolean} Success or not - * @param {number} privilege - New privilege which should be added - * @version 0.13.37 - */ - addPrivilege(privilege) { } - /** - * @description Removes an privilege from an user - * @returns {boolean} Success or not - * @param {number} privilege - Privilege which should be removed - * @version 0.13.37 - */ - removePrivilege(privilege) { } - /** - * @description Deletes an user - * @returns {boolean} Success or not - * @version 0.13.37 - */ - delete() { } -} - -/** - * @class - * @mixin - * @description handles channel, channelgroup and servergroup permissions; mainly for TS3 - * @version 0.13.37 - */ -class Permission { - /** - * @version 0.13.37 - * @returns {string} ID of the permission - */ - id() { } - /** - * @version 0.13.37 - * @returns {string} Name of the permission - */ - name() { } - /** - * @version 0.13.37 - * @returns {number} permission value - */ - value() { } - /** - * @version 0.13.37 - * @returns {boolean} true, if skip flag has been set - only applicable for ServerGroups - */ - skip() { } - /** - * @version 0.13.37 - * @returns {boolean} true, if negated flag has been set - only applicable for ServerGroups - */ - negated() { } - /** - * @description sets the value of the permission; you need to call save() to apply changes - * @version 0.13.37 - * @param {boolean} value - true, if permission should be negated, false otherwise - * @returns {boolean} - */ - setNegated(value) { } - /** - * @description sets the skip flag - only applicable for ServerGroups; you need to call save() to apply changes - * @version 0.13.37 - * @param {boolean} value - true, if permission should be skipped, false otherwise - * @returns {boolean} - */ - setSkip(value) { } - /** - * @description sets the negated flag - only applicable for ServerGroups; you need to call save() to apply changes - * @version 0.13.37 - * @param {number} value - new value for the permission - * @returns {boolean} - */ - setValue(value) { } - /** - * @description applies the changed settings - * @version 0.13.37 - * @returns {boolean} - */ - save() { } - /** - * @description delete the current permission - * @version 0.13.37 - * @returns {boolean} - */ - delete() { } -} - -/** - * @class - * @mixin - */ -class Track { - /** - * @returns {string} Unique ID of the track - */ - id() { } - /** - * @returns {string} Unique url for the track - */ - url() { } - /** - * @returns {string} Type of the file - */ - type() { } - /** - * @returns {string} Title of the track - */ - title() { } - /** - * @returns {string} Artist of the track - */ - artist() { } - /** - * @returns {string} Temporary title of the track; e.g. when playing radio stations - */ - tempTitle() { } - /** - * @returns {string} Temporary artist of the track; e.g. when playing radio stations - */ - tempArtist() { } - /** - * @returns {string} Album of the track - */ - album() { } - /** - * @returns {string} Genre of the track - * @version 0.9.16 - */ - genre() { } - /** - * @returns {number} Duration of the track - * @version 0.9.16 - */ - duration() { } - /** - * @returns {number} Tracknumber of the track - * @version 0.9.16 - */ - trackNumber() { } - /** - * @returns {string} Path to the thumbnail, if any - */ - thumbnail() { } - /** - * @returns {string} Original filename - */ - filename() { } - /** - * @description Starts playback of the track - * @returns {boolean} - */ - play() { } - /** - * @description Adds the track to the queue - * @returns {boolean} - */ - enqueue() { } - // /** - // * @description Adds the track as the first entry in the queue - // * @returns {boolean} - // */ - // playNext: function() {}, - /** - * @description Downloads a thumbnail from the internet and stores it for the given track - * @param {string} url - Url to download the thumbnail from (limited to X MB) - */ - setThumbnailFromURL(url) { } - /** - * @description Removes the thumbnail of a track - */ - removeThumbnail() { } -} - -/** - * @class - * @mixin - */ -class Playlist { - /** - * @returns {string} Unique identifier of the playlist - */ - id() { } - /** - * @returns {string} Name of the playlist - */ - name() { } - /** - * @returns {PlaylistTrack[]} List of all tracks inside the given playlist - */ - getTracks() { } - /** - * @description Sets the playlist to active; will continue playing songs from this playlist - * @returns {boolean} - */ - setActive() { } -} - -/** - * @class - * @mixin - * @description Track in a Playlist - */ -class PlaylistTrack { - /** - * @returns {string} Title of the track - */ - title() { } - /** - * @returns {string} Artist of the track - */ - artist() { } - /** - * @returns {string} Album of the track - */ - album() { } - /** - * @returns {string} Url of the track (internal or external) - */ - url() { } - /** - * @description Starts playback of the track - * @returns {boolean} success - */ - play() { } - // /** - // * adds the track to the queue - // * @returns {boolean} - // */ - // enqueue: function() {}, - // /** - // * adds the track as the first entry in the queue - // * @returns {boolean} - // */ - // playNext: function() {} -} - -/** - * @class - * @mixin - * @version 0.9.16 - */ -class Bytes { - /** - * @returns {string} String representation of the bytes - */ - toString() { } -} - -/** - * @class - * @mixin - */ -class Http { - /** - * @version 0.14.2 - * @description Creates an http request - * @param {object} config - http configuration object - * @param {string} [config.method] - Request Method to use (eg GET, POST, PUT, ...) - * @param {string} config.url - The URL endpoint which should be called - * @param {number} [config.timeout] - timeout in milliseconds - * @param {string} [config.body] - request body - * @param {object} [config.headers] - request header - * @param {Http#SimpleRequestCallback} callback - Callback function with error and response - * @example - * var engine = require('engine'); - * var http = require('http'); - * - * http.simpleRequest({ - * method: 'GET', - * url: 'https://example.com', - * timeout: 10 * 1000 - * }, function(error, response) { - * if (error) { - * engine.log("Error: " + error); - * return; - * } - * - * if (response.statusCode != 200) { - * engine.log("HTTP Error: " + response.status); - * return; - * } - * - * // success! - * engine.log("Response: " + response.data.toString()); - * }); - */ - simpleRequest(config, callback) { } -} -/** - * @callback simpleRequestCallback - * @memberof Http - * @instance - * @see Http#simpleRequest - * @version 0.14.2 - * @param {string} [error] - * @param {object} [response] - * @param {Bytes} response.data - Data; Needs to be converted to a string first, e.g. `response.data.toString()`. - * @param {object} response.headers - Headers - * @param {string} response.status - Status - * @param {number} response.statusCode - Status Code - */ - -/** - * @class - * @mixin - * @version 0.9.16 - * @property {string} [host] - Host to connect to; required for mysql / postgres - * @property {number} [port] - Port to use - * @property {string} [url] - WebSocket URL to use - * @property {string} [protocol=tcp] - can be udp, tcp or ws (websocket) - */ -class ConnectParams { } - -/** - * @class - * @mixin - * @version 0.9.16 - * @fires error - * @fires close - * @fires data - */ -class NetClient { - /** - * @description Sends data over the connection - * @param {(string|number[])} bytes - Data that should be sent over the socket; one can also send an array of ints / bytes like [0, 255, 1, 1] - * @param {string} [format] - Optional, if given bytes will be decoded prior to sending; Can be either "hex" or "base64". - */ - write(bytes, format) { } - /** - * @description Registers a new event handler - * @param {string} event - Name of the event to listen to - * @param {function} callback - */ - on(event, callback) { } - /** - * @description Closes the current connection - */ - close() { } -} - -/** - * @class - * @mixin - * @version 0.9.16 - * @example - * var net = require('net'); - * var engine = require('engine'); - * var conn = net.connect({ host: '127.0.0.1', port: 80 }, function(err) { - * if (err) { engine.log(err); } - * }); - * conn.on('data', function(x) { - * engine.log('got data'); - * engine.log(x.toString()); - * }) - * if (conn) conn.write("GET / HTTP/1.1\r\nHost: localhost\r\n\r\n"); - * @description - * The net module is protected, it needs the following entry per script in your config.ini: - * ``` - * [Scripts.Privileges] - * scriptname = ["net"] - * ``` - */ -class Net { - /** - * @param {ConnectParams} params - Connection parameters - * @param {Net#connectCallback} callback - Callback gets called on success/error. - * @returns {?NetClient} Client connection, or null if failed to setup a connection - * (e.g. wrong parameters; null does not mean that the connection failed, instead that it is handled in the callback) - */ - connect(params, callback) { } -} -/** - * @callback connectCallback - * @memberof Net - * @instance - * @see Net#connect - * @version 0.9.16 - * @description If an error occured, exactly one parameter containing the error will be handed to the callback. - * @param {string} [error] - */ -/** - * @event data - * @memberof NetClient - * @param {Bytes} - * @description Gets fired whenever data is received - */ -/** - * @event close - * @memberof NetClient - * @description Gets fired whenever the connection is closed - */ -/** - * @event error - * @memberof NetClient - * @param {string} error - * @description Gets fired whenever an error occurred - */ - -/** - * @class - * @mixin - * @version 0.9.16 - * @property {string} driver - Database driver to use, currently sqlite3 (currently in-memory only), mysql or postgres - * @property {string} [host] - Database server to connect to, required for mysql / postgres - * @property {string} [username] - * @property {string} [password] - * @property {number} [port] - */ -class DBParams { } - -// TODO: improve parameter documentation -/** - * @class - * @mixin - * @version 0.9.16.4 - */ -class DBConn { - /** - * @description - * Use this, if you expect a result set; - * Note: strings will be returned as byte arrays to be binary safe; to convert to actual strings, please use helpers.toString(column) - * @param {string} queryString - * @param {any} parameter1 - Zero or more parameters; e.g. for mysql, ? in the queryString will be replaced with these parameters - * @param {any} parameter2 - * @param {DBConn#queryCallback} callback - Callback is called after the query has finished. - */ - query(queryString, parameter1, parameter2, callback) { } - /** - * @description Use this insted of query if you don't expect a result - * @param {string} queryString - * @param {any} [parameter1] - * @param {any} [parameter2] - * @param {function} [callback] - */ - exec(queryString, parameter1, parameter2, callback) { } -} -/** - * @callback queryCallback - * @memberof DBConn - * @instance - * @see DBConn#query - * @see DBConn#exec - * @version 0.9.16.4 - * @description Gets called with two parameters, err and result - both are mutually exclusive. - * Result contains an array of rows, each containing an object with the column names as key. - * @param {string} [error] - * @param {object[]} [result] - */ - -/** - * @class - * @mixin - * @version 0.9.16.4 - * @description - * The database module is protected, it needs the following entry per script in your config.ini: - * ``` - * [Scripts.Privileges] - * scriptname = ["db"] - * ``` - * - * Use additional parameters to exec / query whenever you use untrusted/unknown data, as those will automatically be escaped and avoid SQL injection. - * @example - * var db = require('db'); - * var engine = require('engine'); - * var helpers = require('helpers'); - * var dbc = db.connect({ driver: 'mysql', host: '127.0.0.1', username: 'demo', password: 'blah', database: 'foo' }, function(err) { - * if (err) { - * engine.log(err); - * } - * }); - * if (dbc) dbc.exec("INSERT INTO blah (foo, foo2) VALUES (?, ?)", 'bar', 'bar2'); - * if (dbc) dbc.query("SELECT * FROM blah", function(err, res) { - * if (!err) { - * res.forEach(function(row) { - * engine.log(helpers.toString(row.foo)); - * }); - * } - * }); - */ -class DB { - /** - * @param {DBParams} params - Connection parameters - * @param {function} callback - Callback gets called on success / error; - * If an error occured, exactly one parameter containing the error will be handed to the callback - * @returns {?DBConn} Database connection or null if failed - */ - connect(params, callback) { } -} - -/** - * @class - * @mixin - * @version 0.9.20 - * @fires Event~ws.connect - * @fires Event~ws.close - * @fires Event~ws.error - * @fires Event~ws.data - * @description - * Websocket Server: - * The ws module is protected, it needs the following entry per script in your config.ini: - * ``` - * [Scripts.Privileges] - * scriptname = ["ws"] - * ``` - * @example - * SinusBot script: - * var ws = require('ws'); - * var engine = require('engine'); - * var event = require('event'); - * - * event.on('ws.connect', function(id) { - * engine.log('new websocket connection; id ' + id); - * ws.broadcast(1, { blubb: 'blubb' }); - * }); - * event.on('ws.disconnect', function(id) { - * engine.log('websocket connection disconnected; id ' + id); - * }); - * event.on('ws.data', function(id, type, data) { - * engine.log('ws.data: id ' + id + '; data: ' + data.toString()); - * ws.write(id, type, data.toString()); - * }); - * @example - * Client Side (served html files via the enableWeb script option): - * var proto = (window.location.protocol == 'https:') ? 'wss' : 'ws'; - * var conn = new WebSocket(proto + "://" + document.location.host + "/api/v1/b/" + botId + "/i/" + instanceId + "/ws"); - * conn.onclose = function (evt) { - * console.log('close', evt); - * alert('Closed.'); - * }; - * conn.send(JSON.stringify({ type: 'ping' })); - * conn.onmessage = function (evt) { - * var data = JSON.parse(evt.data); - * }; - */ -class WS { - /** - * @description Writes some data to the connection with given connectionId - * @param {string} connectionId - * @param {number} messageType - * @param {(string|Bytes)} message - Actual message; can be given as string or byteshelper - */ - write(connectionId, messageType, message) { } - /** - * @description Broadcasts some data to all connected clients - * @param {number} messageType - * @param {(string|Bytes)} message - Actual message; can be given as string or byteshelper - */ - broadcast(messageType, message) { } - /** - * @description Closes the connection - * @param {string} connectionId - */ - close(connectionId) { } -} - -/** - * @class - * @mixin - * @version 0.14.2 - * @example - * var graphics = require('graphics'); - */ -class Graphics { - /** - * @description Removes the banner. - * @return {boolean} success - */ - removeBanner() { } - /** - * @description Setbanner sets the avatar of the sinusbot client. - * @example - * graphics.setBanner('banner', { - * "format": "png", - * "width": 260, - * "height": 120, - * "layers": layers[] - * }, function() { engine.setAvatarFromBanner('banner.png'); }); - * @param {string} filename - filename without ending - * @param {object} graphicsSettings - * @param {function} callback - * @return {boolean} success - */ - setBanner(filename, graphicsSettings, callback) { } -} - -/** - * @class - * @mixin - * @version 1.0.0 - */ -class FileInfo { - /** - * @version 1.0.0 - * @returns {string} Base name of the file - */ - name() { } - /** - * @version 1.0.0 - * @returns {string} Length in bytes for regular files; system-dependent for others - */ - size() { } - // FIXME: Either document FileMode or change to number - /** - * @version 1.0.0 - * @returns {FileMode} File mode bits - */ - mode() { } - /** - * @version 1.0.0 - * @returns {Date} Modification time - */ - modTime() { } - /** - * @version 1.0.0 - * @returns {boolean} Returns if the file is a directory - */ - isDir() { } - // FIXME: What is returned here exactly? - // /** - // * @returns {object} Underlying data source (can return nil) - // */ - // sys() { } -} - -/** - * @class - * @mixin - * @version 1.0.0 - */ -class FS { - /** - * @description Checks if a file exists - * @version 1.0.0 - * @param {string} path - Path to the file (for example `/var/www/html/foo.txt`) - * @return {boolean} - */ - exists(path) { } - /** - * @description Reads the content of a file - * @version 1.0.0 - * @param {string} path - Path to the file - * @return {Bytes} - */ - readFile(path) { } - /** - * @description Writes data to a file - * @version 1.0.0 - * @param {string} path - Path to the file - * @param {BytesWriter} data - Data as Bytes, e.g. created by `helpers.bytesFromString()` or similar functions - * @param {number} mode - File mode bits - * @return {boolean} success - */ - writeFile(path, data, mode) { } - /** - * @description Returns information about a file - * @version 1.0.0 - * @param {string} path - Path to the file - * @return {FileInfo} FileInfo - */ - stat(path) { } - /** - * @description Returns information about all files in a dirictory - * @version 1.0.0 - * @param {string} path - Path to the directory - * @return {FileInfo[]} Array of FileInfo - */ - readDir(path) { } - /** - * @description Deletes a file or directory - * @version 1.0.0 - * @param {string} path - Path to the file or directory - * @return {boolean} success - */ - remove(path) { } - /** - * @description Creates a directory - * @version 1.0.0 - * @param {string} path - Path of the directory - * @return {boolean} success - */ - mkDir(path) { } - /** - * @description Creates every missing directory in a path - * @version 1.0.0 - * @param {string} path - Path of the directory - * @return {boolean} success - */ - mkDirAll(path) { } - /** - * @description Deletes a file or directory - * @version 1.0.0 - * @param {string} path - Path to the file or directory - * @param {string} newPath - New path to the file or directory - * @return {boolean} success - */ - rename(path, newPath) { } -} \ No newline at end of file diff --git a/api/audio.js b/api/audio.js new file mode 100644 index 0000000..3c78dac --- /dev/null +++ b/api/audio.js @@ -0,0 +1,134 @@ +/** + * @module audio + */ +module.exports = { + /** + * @description Applies an audiofilter to the audio output + * @param {string} filter - ffmpeg compatible filter string + * @returns {boolean} + */ + setAudioFilter: (filter) => {}, + + /** + * @description Enables or disables audio return channel; required for speech recognition engine / recording + * @param {number} flags - bitmask; use 0x01 for general audio return (recording) or 0x02 for separated audio (for speech recognition) - 0x03 for both + * @returns {boolean} + * @version 0.13.37 + */ + setAudioReturnChannel: (flags) => {}, + + /** + * @description Starts recording to a file + * @returns {boolean} + */ + startRecording: () => {}, + + /** + * @description Stops recording to a file + * @returns {boolean} + */ + stopRecording: () => {}, + + /** + * @description Streams audio output to an icecast-server + * @param {string} url - Endpoint to stream to + * @param {string} username - Username used for authentication + * @param {string} password - Password + * @returns {boolean} + */ + streamToServer: (url, username, password) => {}, + + /** + * @description Stops streaming started with streamToServer + * @returns {boolean} + */ + stopStream: () => {}, + + /** + * Returns the state of repeat-mode + * @returns {boolean} + */ + isRepeat: () => {}, + + /** + * @description Sets the state of repeat-mode + * @param {boolean} val + */ + setRepeat: (val) => {}, + + /** + * Returns the state of shuffle-mode + * @returns {boolean} + */ + isShuffle: () => {}, + + /** + * @description Sets the state of shuffle-mode + * @param {boolean} val + */ + setShuffle: (val) => {}, + + /** + * Returns the current volume (0-100) + * @returns {number} volume + */ + getVolume: () => {}, + + /** + * @description Sets the volume (0-100) + * @param {number} volume + * @returns {boolean} + */ + setVolume: (volume) => {}, + + /** + * Returns the position of the current track + * @returns {number} position (in seconds) + */ + getTrackPosition: () => {}, + + /** + * @description Seeks to a specific position + * @param {number} pos - New position (in seconds) + */ + seek: (pos) => {}, + + /** + * Returns if the audio output has been muted + * @returns {boolean} + */ + isMute: () => {}, + + /** + * @description Enables/disables mute + * @param {boolean} mute + * @returns {boolean} + */ + setMute: () => {}, + + /** + * @returns {boolean} Whether the bot is playing music + */ + isPlaying: () => {}, + + /** + * @description Plays audio returned from the text-to-speech engine + * @param {string} text - Text to say + * @param {string} [locale] - Locale to use + */ + say: (text, locale) => {}, + + /** + * @description Returns the client count of the connected server + * @returns {number} client count + */ + getClientCount: () => {}, + + /** + * @description Sets the volume of a specific stream (0-100) + * @param {string} streamID - name or alias of the stream(s) to modify + * @param {number} volume + * @returns {boolean} + */ + setStreamVolume: (streamID, volume) => {}, +} \ No newline at end of file diff --git a/api/backend.js b/api/backend.js new file mode 100644 index 0000000..23e3869 --- /dev/null +++ b/api/backend.js @@ -0,0 +1,197 @@ +/** + * @module backend + */ +module.exports = { + /** + * @description Connects to the server + * @returns {boolean} + */ + connect: () => {}, + + /** + * @description Disconnects from the server + * @returns {boolean} + */ + disconnect: () => {}, + + /** + * Returns true if the backend is connected to a server + * @returns {boolean} + */ + isConnected: () => {}, + + /** + * @returns {string} Current bots' unique identifier + */ + getBotClientID: () => {}, + + /** + * @returns {Client} Client of the bot + */ + getBotClient: () => {}, + + /** + * Returns the actual nickname; To get the configured nickname, use engine.getNick() instead. + * @returns {string} + */ + getNick: () => {}, + + /** + * Returns a channel if found + * @param {string} id + * @returns {Channel} + * @example + * var backend = require('backend'); + * var channel = backend.getChannelByID('6'); + */ + getChannelByID: (id) => {}, + + /** + * Returns the (primary) channel the bot is in + * @returns {Channel} + * @example + * var backend = require('backend'); + * var channel = backend.getCurrentChannel(); + */ + getCurrentChannel: () => {}, + + /** + * Returns the matching channel if found + * @param {string} name + * @returns {Channel?} + * @see Backend#getChannelsByName() + * @example + * var backend = require('backend'); + * var channel = backend.getChannelByName('Welcome Channel'); + */ + getChannelByName: (name) => {}, + + /** + * Returns an array of channels matching the name + * @param {string} name + * @returns {Channel[]} + * @version 0.14.0 + * @example + * var backend = require('backend'); + * var channels = backend.getChannelsByName('foobar'); + */ + getChannelsByName: (name) => {}, + + /** + * Returns the total number of channels + * @returns {number} + * @example + * var backend = require('backend'); + * var count = backend.getChannelCount(); + */ + getChannelCount: () => {}, + + /** + * Returns all channels + * @returns {Channel[]} + * @example + * // Logs the name of all channels + * + * var backend = require('backend'); + * var engine = require('engine'); + * var channels = backend.getChannels(); + * + * channels.forEach(function(channel) { + * engine.log(channel.name()); + * }); + */ + getChannels: () => {}, + + /** + * Returns all clients + * @returns {Client[]} + * @example + * // Gets a list of all clients and sends them a message + * + * var backend = require('backend'); + * var clients = backend.getClients(); + * + * clients.forEach(function(client) { + * client.chat('Hello ', + client.name() + '. I\'m a SinusBot!'); + * }); + */ + getClients: () => {}, + + /** + * Returns a client by its temporary ID (changes when the client reconnects) + * @param {string} id + * @returns {Client} + */ + getClientByID: (id) => {}, + + /** + * Returns a client by its name/nickname + * @param {string} name + * @returns {Client} + */ + getClientByName: (name) => {}, + + /** + * Alias of getClientByName + * @param {string} name + * @returns {Client} + */ + getClientByNick: (name) => {}, + + /** + * Returns an (online) client by its permanent id + * @param {string} uniqueID + * @returns {Client} + */ + getClientByUniqueID: (uniqueID) => {}, + + /** + * Alias of getClientByUniqueID + * @param {string} uniqueID + * @returns {Client} + */ + getClientByUID: (uniqueID) => {}, + + /** + * @description Sends a message to the server + * @param {string} msg - Message to send + * @example + * var backend = require('backend'); + * backend.chat('Hello from SinusBot!'); + */ + chat: (msg) => {}, + + /** + * @description Creates a new channel + * @version 0.9.16.3 + * @param {ChannelParams} channelParams + * @returns {Channel} - Channel which was created + */ + createChannel: (channelParams) => {}, + + /** + * Returns a servergroup by its ID + * @param {string} id ServerGroup ID + * @returns {ServerGroup} + */ + getServerGroupByID: (id) => {}, + + /** + * Returns a channelgroup by its ID + * @param {string} id - ChannelGroup ID + * @returns {ChannelGroup} + */ + getChannelGroupByID: (id) => {}, + + /** + * Returns an array of all known server groups + * @returns {ServerGroup[]} + */ + getServerGroups: () => {}, + + /** + * Returns an array of all known channel groups + * @returns {ChannelGroup[]} + */ + getChannelGroups: () => {}, +} \ No newline at end of file diff --git a/api/db.js b/api/db.js new file mode 100644 index 0000000..702f977 --- /dev/null +++ b/api/db.js @@ -0,0 +1,91 @@ +// TODO: improve parameter documentation +/** + * @interface DBConn + * @version 0.9.16.4 + */ +class DBConn { + /** + * @description + * Use this, if you expect a result set; + * Note: strings will be returned as byte arrays to be binary safe; to convert to actual strings, please use helpers.toString(column) + * @param {string} queryString + * @param {any} [parameters] - Zero or more parameters; e.g. for mysql, ? in the queryString will be replaced with these parameters + * @param {dbQueryCallback} callback - Callback is called after the query has finished. + */ + query(queryString, parameters, callback) {} + + /** + * @description Use this insted of query if you don't expect a result + * @param {string} queryString + * @param {any} [parameters] - Zero or more parameters; e.g. for mysql, ? in the queryString will be replaced with these parameters + * @param {function} [callback] + */ + exec(queryString, parameters, callback) {} +} +/** + * @callback dbQueryCallback + * @see DBConn#query + * @see DBConn#exec + * @version 0.9.16.4 + * @description Gets called with two parameters, err and result - both are mutually exclusive. + * Result contains an array of rows, each containing an object with the column names as key. + * @param {string} [error] + * @param {object[]} [result] + */ + +/** + * @typedef {object} DBParams + * @version 0.9.16 + * @property {string} driver - Database driver to use, sqlite3 (default; currently in-memory only), mysql or postgres + * @property {string} [host] - Database server to connect to, required for mysql / postgres + * @property {string} [username] + * @property {string} [password] + * @property {number} [port] + */ + +/** + * @callback dbConnectCallback + * @see module:db#connect + * @version 0.9.16.4 + * @description If an error occured, exactly one parameter containing the error will be handed to the callback + * @param {string} [error] + */ + +/** + * @module db + * @version 0.9.16.4 + * @description + * The database module is protected, it needs the following entry per script in your config.ini: + * ``` + * [Scripts.Privileges] + * scriptname = ["db"] + * ``` + * + * Use additional parameters to exec / query whenever you use untrusted/unknown data, as those will automatically be escaped and avoid SQL injection. + * @example + * var db = require('db'); + * var engine = require('engine'); + * var helpers = require('helpers'); + * var dbc = db.connect({ driver: 'mysql', host: '127.0.0.1', username: 'demo', password: 'blah', database: 'foo' }, function(err) { + * if (err) { + * engine.log(err); + * } + * }); + * if (dbc) dbc.exec("INSERT INTO blah (foo, foo2) VALUES (?, ?)", 'bar', 'bar2'); + * if (dbc) dbc.query("SELECT * FROM blah", function(err, res) { + * if (!err) { + * res.forEach(function(row) { + * engine.log(helpers.toString(row.foo)); + * }); + * } + * }); + */ +module.exports = { + /** + * @param {DBParams} params - Connection parameters + * @param {dbConnectCallback} callback - Callback gets called on success / error; + * If an error occured, exactly one parameter containing the error will be handed to the callback + * @returns {?DBConn} Database connection or null if failed + */ + connect: (params, callback) => {} +} \ No newline at end of file diff --git a/api/engine.js b/api/engine.js new file mode 100644 index 0000000..c2ebbe8 --- /dev/null +++ b/api/engine.js @@ -0,0 +1,232 @@ +/** + * @module engine + * @example + * var engine = require('engine'); + * engine.log('Hello from a script!'); + */ +module.exports = { + /** + * @returns {string} Current instances' unique identifier + */ + getInstanceID: () => {}, + + /** + * @returns {string} Current bots' unique identifier + */ + getBotID: () => {}, + + /** + * Returns the name of the used backend (e.g. "ts3" or "discord") + * @returns {string} Backend + */ + getBackend: () => {}, + + /** + * @description + * sets the log level of the instance + * ``` + * level | what gets logged + * ------|----------------- + * 0 | no log messages + * 1 | errors only + * 2 | errors and warnings + * 3 | errors, warnings, information + * 4 | ... + * 10 | most verbose + * 11 | most verbose + external backends + * ``` + * @param {number} level - Log level to set + * @returns {boolean} + * + */ + setInstanceLogLevel: (level) => {}, + + /** + * @description + * Sets the log level of the bot + * ``` + * level | what gets logged + * ------|----------------- + * 0 | no log messages + * 1 | errors only + * 2 | errors and warnings + * 3 | errors, warnings, information + * 4 | ... + * 10 | most verbose + * 11 | most verbose + external backends + * ``` + * @param {number} level - Log level to set + * @returns {boolean} + */ + setBotLogLevel: (level) => {}, + + /** + * Returns the log level of the instance + * @returns {number} The set loglevel + */ + getInstanceLogLevel: () => {}, + + /** + * Returns the log level of the bot + * @returns {number} The set loglevel + */ + getBotLogLevel: () => {}, + + /** + * Reloads all scripts; requires the corresponding setting in the config.ini to be enabled + * @returns {boolean} + */ + reloadScripts: () => {}, + + /** + * Returns the configured nickname - to get the actual nickname, use the backend module + * @returns {string} + */ + getNick: () => {}, + + /** + * Sets the nick to a new value and updates it on the server + * @param {string} nick - New nick + * @returns {boolean} + */ + setNick: (nick) => {}, + + /** + * Sets the default channel by its ID + * @param {string} channelID + * @returns {boolean} + */ + setDefaultChannelID: (channelID) => {}, + + /** + * Returns true if the backend of this instance has been started + * @returns {boolean} + */ + isRunning: () => {}, + + /** + * Sends a notification to all users that are currently using the webinterface; use this for startup errors + * @param {string} message - Message to send + */ + notify: (message) => {}, + + /** + * Stores the given object as configuration for the current script + * @param {object} config + * @returns {boolean} + */ + saveConfig: () => {}, + + /** + * Logs to stdout / instance log + * @param {any} log + */ + log: (log) => {}, + + /** + * Exports an object, so other Scripts are able to use functions or values of the Script + * @param {object} obj - object which should get exported + * @example + * // scriptname: exportscript.js + * var engine = require('engine'); + * var publicvariable = 'I get exportet!'; + * engine.export({ + * // returns the value of 'publicvariable' + * get: function get() { + * return publicvariable; + * }, + * // modifies the value of 'publicvariable' + * set: function get(value) { + * publicvariable = value; + * } + * }) + * @example + * var event = require('event'); + * var engine = require('engine'); + * event.on('load', function() { + * // must always be loaded AFTER the 'load' event + * var script = require('exportscript.js'); + * engine.log(script.get()); // logs 'I get exportet!' + * script.set('New Value'); + * engine.log(script.get()); // logs 'New Value' + * }); + */ + export: (obj) => {}, + + /** + * @description + * removes the current avatar image + * @returns {boolean} + */ + removeAvatar: () => {}, + + /** + * @description + * sets the avatar image to the album art of a given track + * @param {Track} track - Track to extract the album art from + * @returns {boolean} + */ + setAvatarFromTrack: (track) => {}, + + /** + * @description + * sets the avatar image to the manually uploaded image + * @returns {boolean} + */ + setDefaultAvatar: () => {}, + + /** + * @description + * sets the avatar to the rendered output of a banner template + * @param {string} bannerName - banner template to use + * @returns {boolean} + * @version 0.12.0 + */ + setAvatarFromBanner: (bannerName) => {}, + + /** + * @description + * sets the avatar to the given image as URL + * @param {string} url - image url + * @returns {boolean} + * @version 0.14.0 + */ + setAvatarFromURL: (url) => {}, + + /** + * @description Gets the users of the SinusBot + * @version 0.13.37 + * @returns {User[]} + */ + getUsers: () => {}, + + /** + * @description Gets a SinusBot user by his ID + * @version 0.13.37 + * @param {string} id - ID of the SinusBot user + * @returns {?User} + */ + getUserById: (id) => {}, + + /** + * @description Gets a Sinusbot user by his name. + * @version 0.13.37 + * @param {string} name - Name of the user + * @returns {?User} + */ + getUserByName: (name) => {}, + + /** + * @description Sets the command prefix. + * @version 0.14.0 + * @param {string} prefix - Command prefix + */ + setCommandPrefix: (prefix) => {}, + + /** + * @description Gets the command prefix. + * @version 0.14.0 + * @returns {string} Command prefix + */ + getCommandPrefix: () => {}, +} \ No newline at end of file diff --git a/api/event.js b/api/event.js new file mode 100644 index 0000000..f86909d --- /dev/null +++ b/api/event.js @@ -0,0 +1,340 @@ +/** + * @event api:eventName + * @memberof event + * @param {ApiEvent} event - API event + * @description Gets fired whenever api: is triggered by via the web api + */ +/** + * @event chat + * @memberof event + * @param {Message} msg - Message + * @description + * This event gets triggered whenever a chat message has been received. + * This also counts for messages from the bot itself, so make sure to check. + * @example + * var event = require('event'); + * var engine = require('engine'); + * + * event.on('chat', function(ev) { + * engine.log('Got message "'+ev.text +'" from '+ ev.client.name()); + * }); + */ +/** + * @event poke + * @memberof event + * @param {Message} msg - Message + * @description Gets fired whenever the bot is poked + * @example + * var event = require('event'); + * var engine = require('engine'); + * + * event.on('poke', function(msg) { + * engine.log('Got poke message "' + msg.text + '" from ' + msg.client.name()); + * }); + */ +/** + * @event typing + * @memberof event + * @param {Client} client - Client that started typing + * @description Gets fired whenever a client starts typing in a chat with the bot + */ +/** + * @event track + * @memberof event + * @param {Track} track + * @description Gets fired whenever a new track starts + */ +/** + * @event trackInfo + * @memberof event + * @param {Track} track + * @description Gets fired whenever a track changes its information (like radio stations) + */ +/** + * @event trackEnd + * @memberof event + * @param {Track} track + * @param {string} callback - Callback string + * @description Gets fired whenever a track has stopped playing + */ +/** + * @event ytdl.success + * @memberof event + * @param {string} url + * @param {string} jobId + * @param {string} trackId + * @description Gets fired whenever a track was successfully downloaded via ytdl + */ +/** + * @event ytdl.error + * @memberof event + * @param {string} url + * @param {string} jobId + * @param {string} trackId + * @description Gets fired whenever a download via ytdl fails + */ +/** + * @event connect + * @memberof event + * @description Gets fired whenever a connection with the server has been established + */ +/** + * @event connectionFailed + * @memberof event + * @param {string} reason + * @description Gets fired whenever the client is unable to connect to a server + */ +/** + * @event disconnect + * @memberof event + * @description Gets fired whenever the bots connection to the server is closed + */ +/** + * @event clientMove + * @memberof event + * @param {MoveInfo} moveInfo + * @description Gets fired whenever a client moves, joins or disconnects + */ +/** + * @event clientNick + * @memberof event + * @param {Client} client + * @param {string} oldNick + * @description Gets fired whenever a clients nickname is changed + */ +/** + * @event clientVisible + * @memberof event + * @param {MoveInfo} moveInfo + * @description Gets fired whenever a client becomes visible to the bot + */ +/** + * @event clientInvisible + * @memberof event + * @param {MoveInfo} moveInfo + * @description Gets fired whenever a client becomes invisible to the bot + */ +/** + * @event clientKicked + * @memberof event + * @param {MoveInfo} moveInfo + * @description Gets fired whenever a client gets kicked from the server + */ +/** + * @event clientKickedFromChannel + * @memberof event + * @param {MoveInfo} moveInfo + * @description Gets fired whenever a client gets kicked from a channel + */ +/** + * @event clientIPAddress + * @memberof event + * @param {Client} client + * @description Gets fired whenever a clients IP address changes or has initially been fetched + */ +/** + * @event clientAway + * @memberof event + * @param {Client} client + * @description Gets fired whenever a client sets himself as away + */ +/** + * @event clientBack + * @memberof event + * @param {Client} client + * @description Gets fired whenever a client removes himself as away + */ +/** + * @event clientRecord + * @memberof event + * @param {Client} client + * @description Gets fired whenever a client starts recording + */ +/** + * @event clientRecordStop + * @memberof event + * @param {Client} client + * @description Gets fired whenever a client stops recording + */ +/** + * @event clientMute + * @memberof event + * @param {Client} client + * @description Gets fired whenever a client mutes his microphone + */ +/** + * @event clientUnmute + * @memberof event + * @param {Client} client + * @description Gets fired whenever a client unmutes his microphone + */ +/** + * @event clientDeaf + * @memberof event + * @version 0.9.18 + * @param {Client} client + * @description Gets fired whenever a client mutes his sound + */ +/** + * @event clientUndeaf + * @memberof event + * @version 0.9.18 + * @param {Client} client + * @description Gets fired whenever a client unmutes his sound + */ +/** + * @event serverGroupAdded + * @memberof event + * @param {ClientServerGroupEvent} event + * @description Gets fired whenever a client got added to a server group + */ +/** + * @event serverGroupRemoved + * @memberof event + * @param {ClientServerGroupEvent} event + * @description Gets fired whenever a client got removed from a server group + */ +/** + * @event channelCreate + * @memberof event + * @param {Channel} channel - Channel that got created + * @param {Client} invoker - Client that created the channel + * @description Gets fired whenever a channel is created + */ +/** + * @event channelUpdate + * @memberof event + * @param {Channel} channel - Channel that got updated + * @param {Client} invoker - Client that updated the channel + * @description Gets fired whenever a channel is updated + */ +/** + * @event channelDelete + * @memberof event + * @param {Channel} channel - Channel that got deleted + * @param {Client} invoker - Client that deleted the channel + * @description Gets fired whenever a channel is deleted + */ +/** + * @event speech + * @memberof event + * @param {object} ev - Event data + * @param {Client} ev.client - Client + * @param {string} ev.text - Recognized text + * @version 0.13.37 + * @description + * This event gets triggered whenever the bot recognizes a voice command that the script registered, assuming: + * 1) SpeechRecognition was installed + * 2) SpeechRecognition is enabled in the config.ini + * 3) The voice command was registered by the script in registerPlugin + * 4) AudioReturnChannel is set to 2 + * + * Check out [the wiki article](https://wiki.sinusbot.com/en:guides:features:speechrecognition) for more the complete list of reqirements and instructions on how to install it. + * @example + * var event = require('event'); + * var engine = require('engine'); + * var audio = require('audio'); + * + * audio.setAudioReturnChannel(2) + * + * event.on('speech', function(ev) { + * engine.log('Got speech command "' + ev.text + '" from ' + ev.client.name()); + * }); + */ +/** + * @event talkerCount + * @memberof event + * @param {number} number - Number of users that are currently talking in the channel + * @description Gets fired whenever the number of users that are currently talking in the channel changes + */ +/** + * @event unload + * @memberof event + * @description Gets fired whenever the script is going to be unloaded or reloaded; use this to clean up or save stuff + */ +/** + * @event load + * @memberof event + * @description Gets fired when all scripts have been loaded + */ +/** + * @event discord:eventName + * @memberof event + * @param {object} ev - Discord event data + * @description + * This event gets triggered whenever a discord event got received. + * Every event will be emitted in uppercase and the spaces will be replaced by underscores. + * All available discord events are documentated here: https://discordapp.com/developers/docs/topics/gateway#events + * @example + * var event = require('event'); + * var engine = require('engine'); + * + * event.on('discord:GUILD_CREATE', function (ev) { + * engine.log('GUILD_CREATE' + JSON.stringify(ev)); + * }); + */ +/** + * @event ws.connect + * @memberof event + * @version 0.9.20 + * @see ws + * @param {string} id - ID of the new connection + */ +/** + * @event ws.close + * @memberof event + * @version 0.9.20 + * @see ws + * @param {string} id - ID of the closed connection + */ +/** + * @event ws.error + * @memberof event + * @version 0.9.20 + * @see ws + * @param {string} id - ID of the connection + * @param {string} error - Error + */ +/** + * @event ws.data + * @memberof event + * @version 0.9.20 + * @see ws + * @param {string} id - ID of the connection + * @param {number} type - Type of the message + * @param {Bytes} data - Data object + */ + + +/** + * @module event + * @example + * var event = require('event'); + * var engine = require('engine'); + * + * event.on('chat', function(ev) { + * engine.log('Got message "'+ev.text +'" from '+ ev.client.name()); + * }) + */ +module.exports = { + /** + * @description Registers an event listener + * @param {string} eventName - Event to listen to + * @param {function} callback - Gets called when the given event is triggered + */ + on: (eventName, callback) => {}, + + /** + * @description Emits an event to the current instance + * @param {string} eventName - Name of the event to be emitted + * @param {object} data - A data object to be sent with the event + */ + emit: (eventName, data) => {}, + + /** + * @description Emits an event to all instances + * @param {string} eventName - Name of the event to be emitted + * @param {object} data - A data object to be sent with the event + */ + broadcast: (eventName, data) => {}, +} diff --git a/api/format.js b/api/format.js new file mode 100644 index 0000000..8d1cb3f --- /dev/null +++ b/api/format.js @@ -0,0 +1,60 @@ +/** + * @module format + */ +module.exports = { + /** + * @description Apply color if the backend supports it + * @param {string} text - Text that should be colored + * @param {string} color - Hex value of color to apply + * @returns {string} Formatted string + * @example + * // Sends a red-colored message to the server chat (requires permission to do so) + * var backend = require('backend'); + * var format = require('format'); + * backend.chat('This is SinusBot writing in ' + format.formatColor('red', '#aa0000')); + */ + color: (text, color) => {}, + + /** + * @description Apply italic formatting to text + * @param {string} text + * @returns {string} Formatted string + * @example + * // Sends a formattes message to the server chat (requires permission to do so) + * var backend = require('backend'); + * var format = require('format'); + * backend.chat('Part of this message is ' + format.italic('italic')); + */ + italic: (text) => {}, + + /** + * @description Apply bold formatting to text + * @param {string} text + * @returns {string} Formatted string + * @example + * // Sends a formattes message to the server chat (requires permission to do so) + * var backend = require('backend'); + * var format = require('format'); + * backend.chat('Part of this message is ' + format.bold('bold')); + */ + bold: (text) => {}, + + /** + * @description Apply underlined formatting to text + * @param {string} text + * @returns {string} Formatted string + * @example + * // Sends a formatted message to the server chat (requires permission to do so) + * var backend = require('backend'); + * var format = require('format'); + * backend.chat('Part of this message is ' + format.underline('underlined')); + */ + underline: (text) => {}, + + /** + * @description Formats text as code + * @param {string} text + * @returns {string} Formatted string + */ + code: (text) => {}, +} \ No newline at end of file diff --git a/api/fs.js b/api/fs.js new file mode 100644 index 0000000..a52d0d1 --- /dev/null +++ b/api/fs.js @@ -0,0 +1,118 @@ +/** + * @interface FileInfo + * @version 1.0.0 + */ +class FileInfo { + /** + * @version 1.0.0 + * @returns {string} Base name of the file + */ + name() { } + /** + * @version 1.0.0 + * @returns {string} Length in bytes for regular files; system-dependent for others + */ + size() { } + // FIXME: Either document FileMode or change to number + /** + * @version 1.0.0 + * @returns {FileMode} File mode bits + */ + mode() { } + /** + * @version 1.0.0 + * @returns {Date} Modification time + */ + modTime() { } + /** + * @version 1.0.0 + * @returns {boolean} Returns if the file is a directory + */ + isDir() { } + // FIXME: What is returned here exactly? + // /** + // * @returns {object} Underlying data source (can return nil) + // */ + // sys() { } +} + +/** + * @module fs + * @version 1.0.0 + */ +module.exports = { + /** + * @description Checks if a file exists + * @version 1.0.0 + * @param {string} path - Path to the file (for example `/var/www/html/foo.txt`) + * @return {boolean} + */ + exists: (path) => {}, + + /** + * @description Reads the content of a file + * @version 1.0.0 + * @param {string} path - Path to the file + * @return {Bytes} + */ + readFile: (path) => {}, + + /** + * @description Writes data to a file + * @version 1.0.0 + * @param {string} path - Path to the file + * @param {BytesWriter} data - Data as Bytes, e.g. created by `helpers.bytesFromString()` or similar functions + * @param {number} mode - File mode bits + * @return {boolean} success + */ + writeFile: (path, data, mode) => {}, + + /** + * @description Returns information about a file + * @version 1.0.0 + * @param {string} path - Path to the file + * @return {FileInfo} FileInfo + */ + stat: (path) => {}, + + /** + * @description Returns information about all files in a dirictory + * @version 1.0.0 + * @param {string} path - Path to the directory + * @return {FileInfo[]} Array of FileInfo + */ + readDir: (path) => {}, + + /** + * @description Deletes a file or directory + * @version 1.0.0 + * @param {string} path - Path to the file or directory + * @return {boolean} success + */ + remove: (path) => {}, + + /** + * @description Creates a directory + * @version 1.0.0 + * @param {string} path - Path of the directory + * @return {boolean} success + */ + mkDir: (path) => {}, + + /** + * @description Creates every missing directory in a path + * @version 1.0.0 + * @param {string} path - Path of the directory + * @return {boolean} success + */ + mkDirAll: (path) => {}, + + /** + * @description Deletes a file or directory + * @version 1.0.0 + * @param {string} path - Path to the file or directory + * @param {string} newPath - New path to the file or directory + * @return {boolean} success + */ + rename: (path, newPath) => {}, +} \ No newline at end of file diff --git a/api/globals.js b/api/globals.js new file mode 100644 index 0000000..62ecf73 --- /dev/null +++ b/api/globals.js @@ -0,0 +1,64 @@ +// TODO: update links + +/** + * @typedef {object} Manifest + * @see registerPlugin + * @param {string} name - Short name of your script + * @param {string} author - Your name and your email address in the form of: `your name ` + * @param {string} description - A longer description - tell the user what exactly your script does + * @param {string} version - Start with something like 1.0 and increase it with every release + * @param {boolean} [autorun] - Set to true, if you want the script to be run on every instance, without the option to disable it. + * @param {string[]} [backends] + * Per default scripts will only be available on TS3 instances. + * If your script supports Discord (or in the future maybe other backends) as well, you have to specify this explicitly by setting this variable to an array containing all backends: `backends: ["ts3", "discord"]` + * @param {boolean} [enableWeb] + * If your script required own web content, you can set enableWeb to true and put files into the ./scripts/scriptname/html directory. + * After restart, the script title will be clickable and lead to an index.html inside that html-directory you just created. + * + * From there you have access to the localStorage variables containing the login and may communicate with the bot api from your own pages. + * @param {string} [engine] - Sets the required engine version (bot version). This uses [Semantic Versioning](https://semver.org). Example: `engine: ">= 0.9.16"` + * @param {boolean} [hidden] + * Hides the script from the settings page. Should be used together with autorun. + * + * Hidden scripts can not have variables (vars), since they'd never be shown and thus not configurable. + * @param {string[]} [requiredModules] + * Using this, you can define which restricted modules the script wants to use. If it's not allowed via the config, the script will not load at all but instead return an error on startup. + * If you only optionally use features from restricted modules, don't use this but provide a fallback in your script. + * @param {object[]} [vars] - More information about the usage of variables can be found [here](https://wiki.sinusbot.com/en:guides:features:scripts:variables). + * @param {string[]} [voiceCommands] + * This parameter is only used for the speech recognition feature and may contain one or more strings that are to be detected for the given script. + * You can find more details on how to use it here: [Speech Recognition](https://wiki.sinusbot.com/en:guides:features:speechrecognition) + */ + + /** + * @callback mainFunction + * @see registerPlugin + * @param {object} [_] - This parameter is deprecated and should not be used anymore. + * @param {object} config - Configuration of the plugin that the user set from within the web interface + * (given you have added anything to the vars field of your script manifest). + * @param {Manifest} meta - Manifest as specified in registerPlugin. + */ +function mainFunction(_, config, meta) {} + +/** + * @description + * This is the first and only top-level function that should be called in your script, + * everything else will be done in the function that is passed to it. + * @example + * registerPlugin({ + * name: 'Demo Script', + * version: '1.0', + * description: 'This example actually does nothing', + * author: 'Author ', + * vars: [] + * }, function(_, config, meta) { + * // your code goes here + * }); + * @param {Manifest} manifest + * The manifest determines which features are available to the script and + * contains metadata and variables that will be shown in the web interface. + * @param {mainFunction} mainFunction + * If the script is activated this function is called when the scripts are loaded. + * The function receives three parameters, the first one (`_`) is deprecated and should not be used anymore. + */ +function registerPlugin(manifest, mainFunction) { } diff --git a/api/graphics.js b/api/graphics.js new file mode 100644 index 0000000..885d098 --- /dev/null +++ b/api/graphics.js @@ -0,0 +1,48 @@ +/** + * @typedef {object} BannerSettings + * @version 0.14.2 + * @property {string} format - e.g. "png" + * @property {number} width + * @property {number} height + * @property {BannerLayer[]} layers + */ + +/** + * TODO: Document Layer Parameters! + * @typedef {object} BannerLayer + * @version 0.14.2 + */ + + /** + * @module graphics + * @version 0.14.2 + * @example + * var graphics = require('graphics'); + */ +module.exports = { + /** + * @description Removes the banner. + * @return {boolean} success + */ + removeBanner: () => {}, + + /** + * @description Setbanner sets the avatar of the sinusbot client. + * @example + * graphics.setBanner('banner', { + * "format": "png", + * "width": 260, + * "height": 120, + * "layers": [ + * // FIXME: layers + * ] + * }, function() { + * engine.setAvatarFromBanner('banner.png'); + * }); + * @param {string} filename - filename without ending + * @param {BannerSettings} bannerSettings + * @param {function} callback + * @return {boolean} success + */ + setBanner: (filename, bannerSettings, callback) => {}, +} \ No newline at end of file diff --git a/api/helpers.js b/api/helpers.js new file mode 100644 index 0000000..1f5376b --- /dev/null +++ b/api/helpers.js @@ -0,0 +1,124 @@ +/** + * @module helpers + */ +module.exports = { + /** + * @description Returns a random numbers between zero and + * @param {number} max + * @returns {number} Random numbers + */ + getRandom: (max) => {}, + + /** + * @description Returns a random permutation of numbers between zero and + * @param {number} max + * @returns {number[]} A random permutation of numbers between zero and + */ + getRandPerm: (max) => {}, + + // TODO: Provide examples how this can be used + // /** + // * @description Creates a new BytesWriter + // * @version 1.0.0 + // * @returns {BytesWriter} + // */ + // newBytes: () => {}, + + /** + * @description Returns a BytesWriter for a given string + * @version 1.0.0 + * @param {string} value String + * @returns {BytesWriter} + */ + bytesFromString: (value) => {}, + + /** + * @description Returns a BytesWriter for a given hex-string + * @version 1.0.0 + * @param {string} value Hex-string + * @returns {BytesWriter} + */ + bytesFromHex: (value) => {}, + + /** + * @description Returns a BytesWriter for a given base64-string + * @version 1.0.0 + * @param {string} value Base64-string + * @returns {BytesWriter} + */ + bytesFromBase64: (value) => {}, + + /** + * @description Encodes a string to base64 + * @param {string} input + * @returns {string} + */ + base64Encode: (input) => {}, + + /** + * @description Decodes a string from base64 + * @param {string} input + * @returns {string} + */ + base64Decode: (input) => {}, + + /** + * @description Encodes a string to hex + * @param {string} input + * @returns {string} + */ + hexEncode: (input) => {}, + + /** + * @description Decodes a string from hex + * @param {string} input + * @returns {string} + */ + hexDecode: (input) => {}, + + /** + * @description Generate a hex-encoded MD5 checksum of the given input + * @param {string} input + * @returns {string} + */ + MD5Sum: (input) => {}, + + /** + * @description Generate a hex-encoded SHA1 checksum of the given input + * @param {string} input + * @returns {string} + */ + SHA1Sum: (input) => {}, + + /** + * @description Generate a hex-encoded SHA256 checksum of the given input + * @param {string} input + * @returns {string} + */ + SHA256Sum: (input) => {}, + + /** + * @description Gets the string representation of an object + * @deprecated This function should not be used anymore, if possible. + * @param input + * @returns {string} + */ + toString: (input) => {}, + + + // Semi-undocumented stuff: + // /** + // * @description Returns the documentation of a function + // * @deprecated Probably doesn't work anymore + // * @returns {string} JSDoc String + // */ + // document: () => {}, + + // /** + // * @description Returns the internal type of an object + // * @deprecated Shouldn't be used + // * @param input + // * @returns {string} Internal type + // */ + // typeOf: (input) => {}, +} \ No newline at end of file diff --git a/api/http.js b/api/http.js new file mode 100644 index 0000000..ff98efa --- /dev/null +++ b/api/http.js @@ -0,0 +1,51 @@ +/** + * @callback simpleRequestCallback + * @see module:http#simpleRequest + * @version 0.14.2 + * @param {string} [error] + * @param {object} [response] + * @param {Bytes} response.data - Data; Needs to be converted to a string first, e.g. `response.data.toString()`. + * @param {object} response.headers - Headers + * @param {string} response.status - Status + * @param {number} response.statusCode - Status Code + */ + +/** + * @module http + */ +module.exports = { + /** + * @version 0.14.2 + * @description Creates an http request + * @param {object} config - http configuration object + * @param {string} [config.method] - Request Method to use (eg GET, POST, PUT, ...) + * @param {string} config.url - The URL endpoint which should be called + * @param {number} [config.timeout] - timeout in milliseconds + * @param {string} [config.body] - request body + * @param {object} [config.headers] - request header + * @param {simpleRequestCallback} callback - Callback function with error and response + * @example + * var engine = require('engine'); + * var http = require('http'); + * + * http.simpleRequest({ + * method: 'GET', + * url: 'https://example.com', + * timeout: 10 * 1000 + * }, function(error, response) { + * if (error) { + * engine.log("Error: " + error); + * return; + * } + * + * if (response.statusCode != 200) { + * engine.log("HTTP Error: " + response.status); + * return; + * } + * + * // success! + * engine.log("Response: " + response.data.toString()); + * }); + */ + simpleRequest(config, callback) { } +} \ No newline at end of file diff --git a/api/media.js b/api/media.js new file mode 100644 index 0000000..7dc2703 --- /dev/null +++ b/api/media.js @@ -0,0 +1,151 @@ +/** + * @module media + */ +module.exports = { + /** + * @description Plays a track via internal url + * @param {string} url - Internal url (like track://...) + * @returns {boolean} + */ + playURL: (url) => {}, + + /** + * Returns the current track + * @returns {Track} + */ + getCurrentTrack: () => {}, + + /** + * Returns the track with the given ID (or null if none was found) + * @returns {?Track} + */ + getTrackByID: (id) => {}, + + /** + * @description Searches for tracks matching the search term, returns 20 entries at most + * @param {string} searchString + * @returns {Track[]} + * @example + * var event = require('event'); + * var media = require('media'); + * + * event.on('chat', function(ev) { + * var params = ev.text.split(' '); + * if (params.length == 1) { + * ev.client.chat('Please enter a searchterm after .play - like .play november rain'); + * return; + * } + * if (params[0] == '.play') { + * params.shift(); + * var results = media.search(params.join(' ')); + * if (results.length > 0) { + * results[0].play(); + * ev.client.chat('Playing - just for you: ' + results[0].artist() + ' - ' + results[0].title()); + * } else { + * ev.client.chat('Sorry, I could not find anything that matched your search.'); + * } + * } + * }); + */ + search: (searchString) => {}, + + /** + * @description Adds the given url to the queue + * @param {string} url + * @returns {boolean} + */ + enqueue: (url) => {}, + + /** + * @description Adds the given url as the first entry in the queue + * @param {string} url + * @returns {boolean} + * @version 0.12.0 + */ + playAsNext: (url) => {}, + + /** + * @description Plays the next track of the queue / playlist + */ + playNext: () => {}, + + /** + * @description Plays the next previous of the queue / playlist + */ + playPrevious: () => {}, + + /** + * @description Stops playback completely + * @param {string} trackID - (optional) the track to stop; if not present, all tracks will be stopped + * @returns {boolean} + */ + stop: (trackID) => {}, + + /** + * Returns all tracks of the queue + * @returns {Track[]} + */ + getQueue: () => {}, + + /** + * Returns all playlists + * @returns {Playlist[]} + */ + getPlaylists: () => {}, + + /** + * Returns the playlists with the given id + * @returns {Playlist} + */ + getPlaylistByID: (id) => {}, + + /** + * Returns the currently active playlist + * @returns {Playlist} + */ + getActivePlaylist: (id) => {}, + + /** + * @description Removes the track at a given position from the queue + * @param {number} index - Index of the track that should be removed from the queue (0 being the first entry) + * @returns {boolean} + */ + removeFromQueue: (index) => {}, + + /** + * @description Removes all entries from the queue + * @returns {boolean} + */ + clearQueue: () => {}, + + /** + * @description Clears the current playlist (if set) so that playback won't continue inside that playlist + * @returns {boolean} + */ + clearPlaylist: () => {}, + + /** + * @description Streams a file via youtube-dl + * @param {string} url - Url that youtube-dl supports + */ + yt: (url) => {}, + + /** + * @description Downloads a file via youtube-dl, optionally plays it + * @param {string} url - Url that youtube-dl supports + * @param {boolean} play - Set to true to play after download + */ + ytdl: (url, play) => {}, + + /** + * @description Enqueues a stream via youtube-dl + * @param {string} url - Url that youtube-dl supports + */ + enqueueYt: (url) => {}, + + /** + * @description Downloads a file via youtube-dl, then enqueues it + * @param {string} url - Url that youtube-dl supports + */ + enqueueYtdl: (url) => {}, +} \ No newline at end of file diff --git a/api/net.js b/api/net.js new file mode 100644 index 0000000..349d110 --- /dev/null +++ b/api/net.js @@ -0,0 +1,90 @@ + +/** + * @interface NetClient + * @version 0.9.16 + */ +class NetClient { + /** + * @description Sends data over the connection + * @param {(string|Bytes|number[])} bytes - Data that should be sent over the socket; one can also send an array of ints / bytes like [0, 255, 1, 1] + * @param {string} [format] - Optional, if given bytes will be decoded prior to sending; Can be either "hex" or "base64". + */ + write(bytes, format) { } + + /** + * @description Registers a new event handler + * @param {string} event - Name of the event to listen to + * @param {function} callback + */ + on(event, callback) { } + + /** + * @description Closes the current connection + */ + close() { } +} +/** + * @event data + * @memberof NetClient + * @param {Bytes} + * @description Gets fired whenever data is received + */ +/** + * @event close + * @memberof NetClient + * @description Gets fired whenever the connection is closed + */ +/** + * @event error + * @memberof NetClient + * @param {string} error + * @description Gets fired whenever an error occurred + */ + +/** + * @typedef {object} NetConnectParams + * @version 0.9.16 + * @property {string} [host] - Host to connect to; required for mysql / postgres + * @property {number} [port] - Port to use + * @property {string} [url] - WebSocket URL to use + * @property {string} [protocol=tcp] - can be udp, tcp or ws (websocket) + */ + +/** + * @callback netConnectCallback + * @see module:net#connect + * @version 0.9.16 + * @description If an error occured, exactly one parameter containing the error will be handed to the callback. + * @param {string} [error] + */ + +/** + * @module net + * @version 0.9.16 + * @example + * var net = require('net'); + * var engine = require('engine'); + * var conn = net.connect({ host: '127.0.0.1', port: 80 }, function(err) { + * if (err) { engine.log(err); } + * }); + * conn.on('data', function(x) { + * engine.log('got data'); + * engine.log(x.toString()); + * }) + * if (conn) conn.write("GET / HTTP/1.1\r\nHost: localhost\r\n\r\n"); + * @description + * The net module is protected, it needs the following entry per script in your config.ini: + * ``` + * [Scripts.Privileges] + * scriptname = ["net"] + * ``` + */ +module.exports = { + /** + * @param {NetConnectParams} params - Connection parameters + * @param {netConnectCallback} callback - Callback gets called on success/error. + * @returns {?NetClient} Client connection, or null if failed to setup a connection + * (e.g. wrong parameters; null does not mean that the connection failed, instead that it is handled in the callback) + */ + connect: (params, callback) => {}, +} \ No newline at end of file diff --git a/api/store.js b/api/store.js new file mode 100644 index 0000000..059fb42 --- /dev/null +++ b/api/store.js @@ -0,0 +1,127 @@ +/** + * @module store + * @example + * var store = require('store'); + * store.set('foo', 'bar'); + */ +module.exports = { + /** + * Stores a variable under the given key + * the values stored are only available for the current script, but shared between instances of it + * @param {string} key + * @param {any} value - Value to be stored; must be JSON.stringify()-able + * @returns {boolean} + * @example + * var store = require('store'); + * store.set('foo', 'bar'); + */ + set: (key, value) => {}, + + /** + * Gets a variable that has been stored previously by set() + * the values stored are only available for the current script, but shared between instances of it + * @param {string} key + * @returns {any} Stored value - or undefined, if not found + * @example + * var store = require('store'); + * var foo = store.get('foo'); + */ + get: (key) => {}, + + /** + * Deletes a stored variable by its key + * the values stored are only available for the current script, but shared between instances of it + * @param {string} key + */ + unset: (key) => {}, + + /** + * Returns an array of all set keys + * the values stored are only available for the current script, but shared between instances of it + * @returns {string[]} Array of all stored keys + */ + getKeys: () => {}, + + /** + * Returns all stored items + * the values stored are only available for the current script, but shared between instances of it + * @returns {object} Keys of this object are the keys of each entry + */ + getAll: () => {}, + + /** + * Stores a variable under the given key + * the values stored are available for every script of every instance + * @param {string} key + * @param {any} value - Value to be stored; must be JSON.stringify()-able + * @returns {boolean} + */ + setGlobal: (key, value) => {}, + + /** + * Gets a variable that has been stored previously by set() + * the values stored are available for every script of every instance + * @param {string} key + * @returns {any} Stored value - or undefined, if not found + */ + getGlobal: (key) => {}, + + /** + * Deletes a stored variable by its key + * the values stored are available for every script of every instance + * @param {string} key + */ + unsetGlobal: (key) => {}, + + /** + * Returns an array of all set keys + * the values stored are available for every script of every instance + * @returns {string[]} Array of all stored keys + */ + getKeysGlobal: () => {}, + + /** + * Returns all stored items + * the values stored are available for every script of every instance + * @returns {object} Keys of this object are the keys of each entry + */ + getAllGlobal: () => {}, + + /** + * Stores a variable under the given key + * the values stored are available only for the current instance of the script (not shared between instances and / or other scripts) + * @param {string} key + * @param {any} value - Value to be stored; must be JSON.stringify()-able + * @returns {boolean} + */ + setInstance: (key, value) => {}, + + /** + * Gets a variable that has been stored previously by set() + * the values stored are available only for the current instance of the script (not shared between instances and / or other scripts) + * @param {string} key + * @returns {any} Stored value - or undefined, if not found + */ + getInstance: (key) => {}, + + /** + * Deletes a stored variable by its key + * the values stored are available only for the current instance of the script (not shared between instances and / or other scripts) + * @param {string} key + */ + unsetInstance: (key) => {}, + + /** + * Returns an array of all set keys + * the values stored are available only for the current instance of the script (not shared between instances and / or other scripts) + * @returns {string[]} Array of all stored keys + */ + getKeysInstance: () => {}, + + /** + * Returns all stored items + * the values stored are available only for the current instance of the script (not shared between instances and / or other scripts) + * @returns {object} Keys of this object are the keys of each entry + */ + getAllInstance: () => {}, +} \ No newline at end of file diff --git a/api/types.js b/api/types.js new file mode 100644 index 0000000..928607d --- /dev/null +++ b/api/types.js @@ -0,0 +1,896 @@ +/**************** + * Interfaces * + ****************/ + +/** + * @interface ApiEvent + * @description This type is passed to a `api:`-event, see [`api:`](#eventeventapieventname) for more. + * @see module:event#api:eventName + */ +class ApiEvent { + /** + * @returns {string} Name of the event + */ + name() { } + /** + * @returns {object} Json body + */ + data() { } + /** + * @returns {?User} User that called the event (or null, if unset) + */ + user() { } + /** + * @returns {string} Remote address that triggered the call + */ + remoteAddr() { } + /** + * @version 0.14 + * @returns {object} Key/Value map of the query parameters in the url + */ + queryParams() { } +} + +/** + * @interface Client + * @description Note: if the client is inivisible to the bot, some fields might not be available. + */ +class Client { + /** + * @returns {string} Name/nickname of the client + */ + name() { } + /** + * Alias of name() + * @returns {string} Name/nickname of the client + */ + nick() { } + /** + * @returns {string} Phonetic name of the client; useful for tts + */ + phoneticName() { } + /** + * @returns {string} Temporary ID of the client + */ + id() { } + /** + * Alias of uniqueId() + * @returns {string} Unique ID of the client + */ + uid() { } + /** + * @returns {string} Unique ID of the client + */ + uniqueId() { } + // TODO: change ID to Id; Support for both versions! + /** + * @returns {string} TeamSpeak database ID of the client + */ + databaseID() { } + /** + * @returns {string} Country of the client + */ + country() { } + /** + * @returns {string} Description of the client + */ + description() { } + /** + * @param {string} description + * @version 0.9.19 + */ + setDescription(description) { } + /** + * @returns {number} Number of times the client has connected + */ + getTotalConnectionsCount() { } + /** + * Returns true when this client is the bot itself + * @returns {boolean} + */ + isSelf() { } + /** + * Returns if the client is recording the conversation + * @returns {string} + */ + isRecording() { } + /** + * Returns if the client is muted (has its microphone disabled) + * @returns {boolean} + */ + isMuted() { } + /** + * Returns if the client is deaf (has its loudspeakers disabled) + * @returns {boolean} + */ + isDeaf() { } + /** + * Returns if the client is away + * @returns {boolean} + */ + isAway() { } + /** + * Returns the clients' servergroups + * @returns {ServerGroup[]} + */ + getServerGroups() { } + /** + * Returns the clients' channelgroup + * @returns {ChannelGroup} + */ + getChannelGroup() { } + /** + * Returns the clients' away message (if set) + * @returns {string} + */ + getAwayMessage() { } + /** + * Returns the clients' last ping time (latency) + * @returns {number} + */ + getPing() { } + /** + * Returns the clients' ip address (if available) + * @returns {string} + */ + getIPAddress() { } + /** + * Returns the clients' online time (requires special permissions) + * @returns {number} in milliseconds + */ + getOnlineTime() { } + /** + * Returns the clients' current idle time (requires special permissions) + * @returns {number} in milliseconds + */ + getIdleTime() { } + /** + * Returns the clients' packet loss percentage (requires special permissions) + * @returns {number} + */ + getPacketLoss() { } + /** + * Returns the clients' amount of received data (requires special permissions) + * @returns {number} + */ + getBytesReceived() { } + /** + * Returns the clients' amount of sent data (requires special permissions) + * @returns {number} + */ + getBytesSent() { } + /** + * Returns the total number of connections from that client + * On TS3, this information has to be actively requested from the server. If the bot is unable to get it or hasn't received an answer in time, it will return <= 0 here. + * @returns {number} + */ + getTotalConnections() { } + /** + * Returns the time the client has been created / was first seen by the server + * On TS3, this information has to be actively requested from the server. If the bot is unable to get it or hasn't received an answer in time, it will return <= 0 here. + * @returns {number} + */ + getCreationTime() { } + /** + * Returns an array of all channels the client is in; even if TS only uses one channel for a client at a time, other backends might provide several + * @returns {Channel[]} Array of channels + */ + getChannels() { } + /** + * @returns {Channel} Current audio channel the client is in + */ + getAudioChannel() { } + /** + * Returns the TS3 client URL in the format `client://0/uid~nickname` + * @returns {string} Client URL + */ + getURL() { } + /** + * @description Compares two clients + * @param {Client} otherClient + * @returns {boolean} true, if both clients are the same + */ + equals(otherClient) { } + /** + * @description Sends a message to the client + * @param {string} msg - Message to send + * @example + * var backend = require('backend'); + * var client = backend.getClientByName('Bob'); + * client.chat('Hello, ' + client.name()); + */ + chat(msg) { } + /** + * @description Pokes the client with a message + * @param {string} msg - Message to send + * @example + * var backend = require('backend'); + * var client = backend.getClientByName('Bob'); + * client.chat('Pokeypoke, ' + client.name() + '!'); + */ + poke(msg) { } + /** + * @description Bans a client + * @param {number} time - Amount of time the ban should last + * @param {string} msg - Message to send + * @example + * var backend = require('backend'); + * var client = backend.getClientByName('Bob'); + * client.ban(100, 'See you in 100 seconds, ' + client.name() + '!'); + */ + ban(time, msg) { } + /** + * @description Kicks the client from the server + * @param {string} msg - Message to send + */ + kick(msg) { } + /** + * @description Kicks the client from the server + * @param {string} msg - Message to send + */ + kickFromServer(msg) { } + /** + * @description Kicks the client from the channel + * @param {string} msg - Message to send + */ + kickFromChannel(msg) { } + /** + * @description Adds a client to a specific ServerGroup + * @param {(ServerGroup|string|number)} group - Servergroup the client should be added to + */ + addToServerGroup(group) { } + /** + * @description Removes a client from a specific ServerGroup + * @param {(ServerGroup|string|number)} group - Servergroup the client should be removed from + */ + removeFromServerGroup(id) { } + /** + * @description + * Moves a client to another channel + * + * *Note: This can also be used to disconnect a discord bot-instance from the voice chat with `backend.getBotClient().moveTo('')`. + * @param {Channel} target - Channel the client should be moved to + * @param {string} [password] - Password for the target channel, if required + */ + moveTo(target, password) { } + /** + * @description Enables / disables subscription for this client; requires subscription mode + * @param {boolean} val + */ + setSubscription(val) { } + /** + * @description Returns the platform of the client (Windows, Linux, MacOS) + * @returns {string} platform + */ + getPlatform() { } + /** + * @description Returns the version of the client + * @returns {string} version + */ + getVersion() { } + /** + * @description Returns the client type (Query=0; Normal=1) + * @returns {string} client type + */ + type() { } +} + +/** + * @interface Channel + */ +class Channel { + /** + * @returns {string} ID + */ + id() { } + /** + * @returns {string} Name + */ + name() { } + /** + * @returns {?Channel} Parent of channel or null if none is set + */ + parent() { } + /** + * @version 0.9.16.3 + * @returns {number} Order / position of this channel. + * For ts3 this is a numeric value determining the order in which channels are displayed below their parent. To set a new value, please use moveTo. + */ + position() { } + /** + * @description delete the current channel + * @version 0.9.17 + * @returns {boolean} + */ + delete() { } + /** + * @description Moves the channel to a new parent with a new position value + * @version 0.9.16.3 + * @param {(string|Channel)} parent - New parent channel + * @param {number} order - New order value + */ + moveTo(parent, order) { } + /** + * @param {string} name + * @version 0.9.16 + */ + setName(name) { } + /** + * @returns {number} Type (0 = voice, 1 = text) + */ + type() { } + /** + * @returns {string} Topic + */ + topic() { } + /** + * @param {string} topic + * @version 0.9.16 + */ + setTopic(topic) { } + /** + * @version 0.9.19 + * @returns {string} Description + */ + description() { } + /** + * @param {string} description + * @version 0.9.16 + */ + setDescription(description) { } + /** + * @returns {number} Codec + */ + codec() { } + /** + * @param {number} codec + * @version 0.9.16 + */ + setCodec(codec) { } + /** + * @returns {number} Codec quality + */ + codecQuality() { } + /** + * @param {number} quality + * @version 0.9.16 + */ + setCodecQuality(quality) { } + /** + * @returns {number} Configured number of clients the channel can hold (-1 if unlimited) + */ + maxClients() { } + /** + * @param {boolean} maxClients Set to -1 for unlimited clients + * @version 0.9.16 + */ + setMaxClients(maxClients) { } + /** + * @returns {number} + */ + maxFamilyClients() { } + /** + * @param {boolean} maxFamilyClients + * @version 0.9.16 + */ + setMaxFamilyClients(maxFamilyClients) { } + /** + * @returns {boolean} Whether channel is permanent or not + */ + isPermanent() { } + /** + * @param {boolean} permanent + * @version 0.9.16 + */ + setPermanent(permanent) { } + /** + * @returns {boolean} Whether channel is semi-permanent or not + */ + isSemiPermanent() { } + /** + * @param {boolean} permanent + * @version 0.9.16 + */ + setSemiPermanent(permanent) { } + /** + * @returns {boolean} Whether channel is the default one + */ + isDefault() { } + /** + * @returns {boolean} Whether channel is password-protected or not + */ + isPassworded() { } + /** + * @returns {boolean} Whether channel is encrypted or not + */ + isEncrypted() { } + /** + * @param {boolean} encrypted + * @version 0.9.16 + */ + setEncrypted(encrypted) { } + /** + * @description Compares two channels + * @param {Channel} otherChannel + * @returns {boolean} True, if both channels are the same + */ + equals(otherChannel) { } + /** + * @description Sends a chat message to the channel + * @param {string} msg - Message to send + */ + chat(msg) { } + /** + * @returns {Client[]} Clients that are in this channel + */ + getClients() { } + /** + * @returns {number} Number of clients that are in the channel + */ + getClientCount() { } + /** + * @description enables / disables subscription for this channel; requires subscription mode + * @param {boolean} val + */ + setSubscription(val) { } + /** + * @description Updates multiple channel parameters at once + * @version 0.9.16.3 + * @param {ChannelParams} channelParams + */ + update(channelParams) { } + /** + * @description Assigns a client to a channel group + * @version 0.9.18 + * @param {Client} client + * @param {ChannelGroup} channelGroup + */ + setChannelGroup(client, channelGroup) { } + /** + * @description Gets the permissions for the channel from the server - this is an expensive call as the permissions are _not_ cached + * @version 0.13.37 + * @returns {Permission[]} + */ + getPermissions() { } + /** + * @description Adds/sets a new permission on the channel; you need to use the setters and then call save() to apply - can also be used to remove a permission by delete() afterwards + * @version 0.13.37 + * @param {string} id - id of the permission to add; can also be supplied as name like i_channel_needed_join_power + * @returns {Permission} + */ + addPermission(id) { } +} + +/** + * @interface ServerGroup + */ +class ServerGroup { + /** + * @returns {string} ID of the server group + */ + id() { } + /** + * @returns {string} Name of the server group + */ + name() { } + /** + * @returns {string} ID of the icon used for the channel group + * @version 0.12.0 + */ + icon() { } + /** + * @description Adds a client by database ID to the servergroup + * @returns {boolean} status if the request was successful + * @version 0.13.37 + * @param {(Client|string|number)} client - The client can be a client object, string or number + */ + addClientByDatabaseId(client) { } + /** + * @description Gets the permissions for the servergroup from the server - this is an expensive call as the permissions are _not_ cached + * @version 0.13.37 + * @returns {Permission[]} + */ + getPermissions() { } + /** + * @description Adds/sets a new permission to the servergroup; you need to use the setters and then call save() to apply - can also be used to remove a permission by delete() afterwards + * @version 0.13.37 + * @param {string} id - id of the permission to add; can also be supplied as name like i_channel_needed_join_power + * @returns {Permission} + */ + addPermission(id) { } +} + +/** + * @interface ChannelGroup + */ +class ChannelGroup { + /** + * @returns {string} ID of the channel group + */ + id() { } + /** + * @returns {string} Name of the channel group + */ + name() { } + /** + * @returns {string} ID of the icon used for the channel group + * @version 0.12.0 + */ + icon() { } + /** + * @description Gets the permissions for the channelgroup from the server - this is an expensive call as the permissions are _not_ cached + * @version 0.13.37 + * @returns {Permission[]} + */ + getPermissions() { } + /** + * @description Adds/sets a new permission to the channelgroup; you need to use the setters and then call save() to apply - can also be used to remove a permission by delete() afterwards + * @version 0.13.37 + * @param {string} id - id of the permission to add; can also be supplied as name like i_channel_needed_join_power + * @returns {Permission} + */ + addPermission(id) { } +} + +/** + * @interface User + */ +class User { + /** + * @description Returns the ID of the user + * @returns {string} ID of the User + * @version 0.13.37 + */ + id() { } + /** + * @description Returns the name of the user + * @returns {string} Name of the User + * @version 0.13.37 + */ + name() { } + /** + * @description Returns the privileges of the user + * @returns {number} Privileges of the user + * @version 0.13.37 + */ + privileges() { } + /** + * @description Returns the teamspeak unique ID of the bind client + * @returns {string} teamspeak unique ID of the bind ts client + * @version 0.13.37 + */ + tsUid() { } + /** + * @description Returns the teamspeak group ID + * @returns {string} ID of the bind teamspeak group + * @version 0.13.37 + */ + tsGroupId() { } + /** + * @description Checks if an user is an admin + * @returns {boolean} Admin status of the user + * @version 0.13.37 + */ + isAdmin() { } + /** + * @description Sets a new password to the user + * @returns {boolean} Success or not + * @param {string} password - new password of the user + * @version 0.13.37 + */ + setPassword(password) { } + /** + * @description Sets the teamspeak unique ID to the user + * @returns {boolean} Success or not + * @param {string} tsUid - teamspeak unique ID of the client + * @version 0.13.37 + */ + setTSUid(tsUid) { } + /** + * @description Sets the privileges to an user + * @returns {boolean} Success or not + * @param {number} privileges - New privileges of the user + * @version 0.13.37 + */ + setPrivileges(privileges) { } + /** + * @description Adds an privilege to an user + * @returns {boolean} Success or not + * @param {number} privilege - New privilege which should be added + * @version 0.13.37 + */ + addPrivilege(privilege) { } + /** + * @description Removes an privilege from an user + * @returns {boolean} Success or not + * @param {number} privilege - Privilege which should be removed + * @version 0.13.37 + */ + removePrivilege(privilege) { } + /** + * @description Deletes an user + * @returns {boolean} Success or not + * @version 0.13.37 + */ + delete() { } +} + +/** + * @interface Permission + * @description handles channel, channelgroup and servergroup permissions; mainly for TS3 + * @version 0.13.37 + */ +class Permission { + /** + * @version 0.13.37 + * @returns {string} ID of the permission + */ + id() { } + /** + * @version 0.13.37 + * @returns {string} Name of the permission + */ + name() { } + /** + * @version 0.13.37 + * @returns {number} permission value + */ + value() { } + /** + * @version 0.13.37 + * @returns {boolean} true, if skip flag has been set - only applicable for ServerGroups + */ + skip() { } + /** + * @version 0.13.37 + * @returns {boolean} true, if negated flag has been set - only applicable for ServerGroups + */ + negated() { } + /** + * @description sets the value of the permission; you need to call save() to apply changes + * @version 0.13.37 + * @param {boolean} value - true, if permission should be negated, false otherwise + * @returns {boolean} + */ + setNegated(value) { } + /** + * @description sets the skip flag - only applicable for ServerGroups; you need to call save() to apply changes + * @version 0.13.37 + * @param {boolean} value - true, if permission should be skipped, false otherwise + * @returns {boolean} + */ + setSkip(value) { } + /** + * @description sets the negated flag - only applicable for ServerGroups; you need to call save() to apply changes + * @version 0.13.37 + * @param {number} value - new value for the permission + * @returns {boolean} + */ + setValue(value) { } + /** + * @description applies the changed settings + * @version 0.13.37 + * @returns {boolean} + */ + save() { } + /** + * @description delete the current permission + * @version 0.13.37 + * @returns {boolean} + */ + delete() { } +} + +/** + * @interface Track + */ +class Track { + /** + * @returns {string} Unique ID of the track + */ + id() { } + /** + * @returns {string} Unique url for the track + */ + url() { } + /** + * @returns {string} Type of the file + */ + type() { } + /** + * @returns {string} Title of the track + */ + title() { } + /** + * @returns {string} Artist of the track + */ + artist() { } + /** + * @returns {string} Temporary title of the track; e.g. when playing radio stations + */ + tempTitle() { } + /** + * @returns {string} Temporary artist of the track; e.g. when playing radio stations + */ + tempArtist() { } + /** + * @returns {string} Album of the track + */ + album() { } + /** + * @returns {string} Genre of the track + * @version 0.9.16 + */ + genre() { } + /** + * @returns {number} Duration of the track + * @version 0.9.16 + */ + duration() { } + /** + * @returns {number} Tracknumber of the track + * @version 0.9.16 + */ + trackNumber() { } + /** + * @returns {string} Path to the thumbnail, if any + */ + thumbnail() { } + /** + * @returns {string} Original filename + */ + filename() { } + /** + * @description Starts playback of the track + * @returns {boolean} + */ + play() { } + /** + * @description Adds the track to the queue + * @returns {boolean} + */ + enqueue() { } + // /** + // * @description Adds the track as the first entry in the queue + // * @returns {boolean} + // */ + // playNext: function() {}, + /** + * @description Downloads a thumbnail from the internet and stores it for the given track + * @param {string} url - Url to download the thumbnail from (limited to X MB) + */ + setThumbnailFromURL(url) { } + /** + * @description Removes the thumbnail of a track + */ + removeThumbnail() { } +} + +/** + * @interface Playlist + */ +class Playlist { + /** + * @returns {string} Unique identifier of the playlist + */ + id() { } + /** + * @returns {string} Name of the playlist + */ + name() { } + /** + * @returns {PlaylistTrack[]} List of all tracks inside the given playlist + */ + getTracks() { } + /** + * @description Sets the playlist to active; will continue playing songs from this playlist + * @returns {boolean} + */ + setActive() { } +} + +/** + * @interface PlaylistTrack + * @description Track in a Playlist + */ +class PlaylistTrack { + /** + * @returns {string} Title of the track + */ + title() { } + /** + * @returns {string} Artist of the track + */ + artist() { } + /** + * @returns {string} Album of the track + */ + album() { } + /** + * @returns {string} Url of the track (internal or external) + */ + url() { } + /** + * @description Starts playback of the track + * @returns {boolean} success + */ + play() { } + // /** + // * adds the track to the queue + // * @returns {boolean} + // */ + // enqueue: function() {}, + // /** + // * adds the track as the first entry in the queue + // * @returns {boolean} + // */ + // playNext: function() {} +} + +/** + * @interface Bytes + * @version 0.9.16 + */ +class Bytes { + /** + * @returns {string} String representation of the bytes + */ + toString() { } +} + +//@interface + +/*********** + * Types * + ***********/ + +/** + * @typedef {object} Message + * @property {string} text - Text of the message + * @property {Channel} channel - Channel (if given) this message has been sent on + * @property {Client} client - Client that sent the message + * @property {number} mode - Number representing the way this message has been sent + * (1 = private, 2 = channel, 3 = server) + */ + +/** + * @typedef {object} MoveInfo + * @property {Channel} [fromChannel] - Old channel (or null if the client just got online/changed visibility) + * @property {Channel} [toChannel] - New channel (or null if the client just went offline/changed visibility) + * @property {Client} client - Client that was moved + * @property {Client} invoker - Client that invoked the move + */ + +/** + * @typedef {object} ClientServergroupEvent + * @property {Client} client - Client that has been added / removed + * @property {Client} invoker - Client that added client to the group + * @property {ServerGroup} serverGroup - Server Group + */ + +/** + * @typedef {object} ChannelParams + * @property {string} name - Displayname of the channel; mandatory on create + * @property {(Channel|number|string)} parent - Parent channel (you can also use the channelId); ignored on update, mandatory on create + * @property {string} description + * @property {string} topic + * @property {string} password + * @property {number} codec - See codec types for explanation + * @property {number} codecQuality + * @property {boolean} encrypted - `true` by default + * @property {boolean} permanent + * @property {boolean} semiPermanent + * @property {number} position + * @property {number} maxClients - Set to `-1` for unlimited clients + * @property {number} maxFamilyClients + * @property {boolean} default - Whether the channel is the default channel + * @property {number} neededTalkPower - TS3 only + * @property {number} deleteDelay - TS3 only + * @property {number} icon - TS3 only + * @description + * Used to update or create a channel; + * When creating a channel parent and name are mandatory for TS3; + * When updating a channel parent will be ignored (use moveTo instead) + */ + +//@typedef {object} \ No newline at end of file diff --git a/api/ws.js b/api/ws.js new file mode 100644 index 0000000..2ed8912 --- /dev/null +++ b/api/ws.js @@ -0,0 +1,66 @@ +/** + * @module ws + * @version 0.9.20 + * @fires event#event:ws.connect + * @fires event#event:ws.close + * @fires event#event:ws.error + * @fires event#event:ws.data + * @description + * Websocket Server: + * The ws module is protected, it needs the following entry per script in your config.ini: + * ``` + * [Scripts.Privileges] + * scriptname = ["ws"] + * ``` + * @example + * SinusBot script: + * var ws = require('ws'); + * var engine = require('engine'); + * var event = require('event'); + * + * event.on('ws.connect', function(id) { + * engine.log('new websocket connection; id ' + id); + * ws.broadcast(1, { blubb: 'blubb' }); + * }); + * event.on('ws.disconnect', function(id) { + * engine.log('websocket connection disconnected; id ' + id); + * }); + * event.on('ws.data', function(id, type, data) { + * engine.log('ws.data: id ' + id + '; data: ' + data.toString()); + * ws.write(id, type, data.toString()); + * }); + * @example + * Client Side (served html files via the enableWeb script option): + * var proto = (window.location.protocol == 'https:') ? 'wss' : 'ws'; + * var conn = new WebSocket(proto + "://" + document.location.host + "/api/v1/b/" + botId + "/i/" + instanceId + "/ws"); + * conn.onclose = function (evt) { + * console.log('close', evt); + * alert('Closed.'); + * }; + * conn.send(JSON.stringify({ type: 'ping' })); + * conn.onmessage = function (evt) { + * var data = JSON.parse(evt.data); + * }; + */ +module.exports = { + /** + * @description Writes some data to the connection with given connectionId + * @param {string} connectionId + * @param {number} messageType + * @param {(string|Bytes)} message - Actual message; can be given as string or byteshelper + */ + write: (connectionId, messageType, message) => {}, + + /** + * @description Broadcasts some data to all connected clients + * @param {number} messageType + * @param {(string|Bytes)} message - Actual message; can be given as string or byteshelper + */ + broadcast: (messageType, message) => {}, + + /** + * @description Closes the connection + * @param {string} connectionId + */ + close: (connectionId) => {}, +} \ No newline at end of file diff --git a/apply_favicon.sed b/apply_favicon.sed new file mode 100644 index 0000000..c5fd6bd --- /dev/null +++ b/apply_favicon.sed @@ -0,0 +1,3 @@ +# insert the favicon meta tag before the head closing tag +/<\/head>/i\ + diff --git a/config.json b/config.json index e619474..9a25122 100644 --- a/config.json +++ b/config.json @@ -1,11 +1,11 @@ { "opts": { - "template": "./node_modules/tsd-jsdoc", + "template": "./node_modules/tsd-jsdoc/dist", "destination": "./tsd" }, "source": { "include": [ - "api.js" + "api/" ] } } \ No newline at end of file diff --git a/documentation.yml b/documentation.yml index d7b2d57..7dbd3d7 100644 --- a/documentation.yml +++ b/documentation.yml @@ -14,23 +14,21 @@ toc: - name: modules description: | Modules which can be imported via `require()` - - Engine - - Store - - Backend - - Media - - Audio - - Format - - Helpers - - Event - - Http - - Net - - WS - - DB - - FS - - Graphics - - name: classes - description: | - Classes which get returned by functions and are not directly accessible + - engine + - store + - backend + - media + - audio + - format + - helpers + - event + - http + - net + - ws + - db + - fs + - graphics + - name: interfaces - Client - Channel - User @@ -40,19 +38,22 @@ toc: - Bytes - PlaylistTrack - Track - - APIEvent + - ApiEvent - Playlist - NetClient - DBConn - - DBConn - FileInfo -# - BytesWriter - name: types - description: | - Type definitions - ClientServergroupEvent - Message - - DBParams - MoveInfo - ChannelParams - - ConnectParams \ No newline at end of file + - NetConnectParams + - DBParams + - BannerSettings + - BannerLayer + - name: callbacks + - simpleRequestCallback + - netConnectCallback + - dbConnectCallback + - dbQueryCallback \ No newline at end of file diff --git a/generate.js b/generate.js deleted file mode 100644 index 4c266ef..0000000 --- a/generate.js +++ /dev/null @@ -1,33 +0,0 @@ -const fs = require("fs") -const os = require('os') - -let modules = [ - "backend", - "event", - "engine", - "ws", - "net", - "db", - "store", - "format", - "audio", - "media", - "helpers" -] - -let appendix = "declare var require: any;" -modules.forEach(moduleName => { - appendix += os.EOL + os.EOL + - `declare var ${moduleName}: ${moduleName[0].toUpperCase() + moduleName.substr(1)}; -declare module "${moduleName}" { - export = ${moduleName}; -}` -}) - -fs.appendFile("tsd/types.d.ts", appendix, err => { - if (err) { - console.error(`Failed to append module exports: ${err.message}`) - return - } - console.log("Successfully appended module exports") -}) \ No newline at end of file diff --git a/package.json b/package.json index 6ad707f..e7ca39b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "sinusbot-scripting-engine", - "version": "1.0.5", + "version": "1.0.6", "description": "SinusBot JavaScript based Scripting Engine documentation with examples.", "repository": "https://github.com/SinusBot/scripting-docs", "homepage": "https://github.com/SinusBot/scripting-docs", @@ -8,7 +8,7 @@ "license": "MIT", "devDependencies": { "jsdoc": "^3.5.5", - "tsd-jsdoc": "=2.0.0-beta.3" + "tsd-jsdoc": "^2.1.3" }, "typings": "./tsd/types.d.ts" } From 5f65b01f03f7e934961cd980ccc4e94437a8230f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20B=C3=B6gle?= Date: Thu, 14 Feb 2019 02:06:48 +0100 Subject: [PATCH 02/11] fix: use @since --- api/audio.js | 2 +- api/backend.js | 4 +- api/db.js | 10 ++--- api/engine.js | 14 +++---- api/event.js | 14 +++---- api/fs.js | 32 +++++++------- api/graphics.js | 6 +-- api/helpers.js | 8 ++-- api/http.js | 4 +- api/media.js | 2 +- api/net.js | 8 ++-- api/types.js | 108 ++++++++++++++++++++++++------------------------ api/ws.js | 2 +- 13 files changed, 107 insertions(+), 107 deletions(-) diff --git a/api/audio.js b/api/audio.js index 3c78dac..50a5e4d 100644 --- a/api/audio.js +++ b/api/audio.js @@ -13,7 +13,7 @@ module.exports = { * @description Enables or disables audio return channel; required for speech recognition engine / recording * @param {number} flags - bitmask; use 0x01 for general audio return (recording) or 0x02 for separated audio (for speech recognition) - 0x03 for both * @returns {boolean} - * @version 0.13.37 + * @since 0.13.37 */ setAudioReturnChannel: (flags) => {}, diff --git a/api/backend.js b/api/backend.js index 23e3869..554d2e8 100644 --- a/api/backend.js +++ b/api/backend.js @@ -70,7 +70,7 @@ module.exports = { * Returns an array of channels matching the name * @param {string} name * @returns {Channel[]} - * @version 0.14.0 + * @since 0.14.0 * @example * var backend = require('backend'); * var channels = backend.getChannelsByName('foobar'); @@ -163,7 +163,7 @@ module.exports = { /** * @description Creates a new channel - * @version 0.9.16.3 + * @since 0.9.16.3 * @param {ChannelParams} channelParams * @returns {Channel} - Channel which was created */ diff --git a/api/db.js b/api/db.js index 702f977..0e95459 100644 --- a/api/db.js +++ b/api/db.js @@ -1,7 +1,7 @@ // TODO: improve parameter documentation /** * @interface DBConn - * @version 0.9.16.4 + * @since 0.9.16.4 */ class DBConn { /** @@ -26,7 +26,7 @@ class DBConn { * @callback dbQueryCallback * @see DBConn#query * @see DBConn#exec - * @version 0.9.16.4 + * @since 0.9.16.4 * @description Gets called with two parameters, err and result - both are mutually exclusive. * Result contains an array of rows, each containing an object with the column names as key. * @param {string} [error] @@ -35,7 +35,7 @@ class DBConn { /** * @typedef {object} DBParams - * @version 0.9.16 + * @since 0.9.16 * @property {string} driver - Database driver to use, sqlite3 (default; currently in-memory only), mysql or postgres * @property {string} [host] - Database server to connect to, required for mysql / postgres * @property {string} [username] @@ -46,14 +46,14 @@ class DBConn { /** * @callback dbConnectCallback * @see module:db#connect - * @version 0.9.16.4 + * @since 0.9.16.4 * @description If an error occured, exactly one parameter containing the error will be handed to the callback * @param {string} [error] */ /** * @module db - * @version 0.9.16.4 + * @since 0.9.16.4 * @description * The database module is protected, it needs the following entry per script in your config.ini: * ``` diff --git a/api/engine.js b/api/engine.js index c2ebbe8..3b624b1 100644 --- a/api/engine.js +++ b/api/engine.js @@ -180,7 +180,7 @@ module.exports = { * sets the avatar to the rendered output of a banner template * @param {string} bannerName - banner template to use * @returns {boolean} - * @version 0.12.0 + * @since 0.12.0 */ setAvatarFromBanner: (bannerName) => {}, @@ -189,20 +189,20 @@ module.exports = { * sets the avatar to the given image as URL * @param {string} url - image url * @returns {boolean} - * @version 0.14.0 + * @since 0.14.0 */ setAvatarFromURL: (url) => {}, /** * @description Gets the users of the SinusBot - * @version 0.13.37 + * @since 0.13.37 * @returns {User[]} */ getUsers: () => {}, /** * @description Gets a SinusBot user by his ID - * @version 0.13.37 + * @since 0.13.37 * @param {string} id - ID of the SinusBot user * @returns {?User} */ @@ -210,7 +210,7 @@ module.exports = { /** * @description Gets a Sinusbot user by his name. - * @version 0.13.37 + * @since 0.13.37 * @param {string} name - Name of the user * @returns {?User} */ @@ -218,14 +218,14 @@ module.exports = { /** * @description Sets the command prefix. - * @version 0.14.0 + * @since 0.14.0 * @param {string} prefix - Command prefix */ setCommandPrefix: (prefix) => {}, /** * @description Gets the command prefix. - * @version 0.14.0 + * @since 0.14.0 * @returns {string} Command prefix */ getCommandPrefix: () => {}, diff --git a/api/event.js b/api/event.js index f86909d..8999f09 100644 --- a/api/event.js +++ b/api/event.js @@ -171,14 +171,14 @@ /** * @event clientDeaf * @memberof event - * @version 0.9.18 + * @since 0.9.18 * @param {Client} client * @description Gets fired whenever a client mutes his sound */ /** * @event clientUndeaf * @memberof event - * @version 0.9.18 + * @since 0.9.18 * @param {Client} client * @description Gets fired whenever a client unmutes his sound */ @@ -221,7 +221,7 @@ * @param {object} ev - Event data * @param {Client} ev.client - Client * @param {string} ev.text - Recognized text - * @version 0.13.37 + * @since 0.13.37 * @description * This event gets triggered whenever the bot recognizes a voice command that the script registered, assuming: * 1) SpeechRecognition was installed @@ -276,21 +276,21 @@ /** * @event ws.connect * @memberof event - * @version 0.9.20 + * @since 0.9.20 * @see ws * @param {string} id - ID of the new connection */ /** * @event ws.close * @memberof event - * @version 0.9.20 + * @since 0.9.20 * @see ws * @param {string} id - ID of the closed connection */ /** * @event ws.error * @memberof event - * @version 0.9.20 + * @since 0.9.20 * @see ws * @param {string} id - ID of the connection * @param {string} error - Error @@ -298,7 +298,7 @@ /** * @event ws.data * @memberof event - * @version 0.9.20 + * @since 0.9.20 * @see ws * @param {string} id - ID of the connection * @param {number} type - Type of the message diff --git a/api/fs.js b/api/fs.js index a52d0d1..c0799f6 100644 --- a/api/fs.js +++ b/api/fs.js @@ -1,31 +1,31 @@ /** * @interface FileInfo - * @version 1.0.0 + * @since 1.0.0 */ class FileInfo { /** - * @version 1.0.0 + * @since 1.0.0 * @returns {string} Base name of the file */ name() { } /** - * @version 1.0.0 + * @since 1.0.0 * @returns {string} Length in bytes for regular files; system-dependent for others */ size() { } // FIXME: Either document FileMode or change to number /** - * @version 1.0.0 + * @since 1.0.0 * @returns {FileMode} File mode bits */ mode() { } /** - * @version 1.0.0 + * @since 1.0.0 * @returns {Date} Modification time */ modTime() { } /** - * @version 1.0.0 + * @since 1.0.0 * @returns {boolean} Returns if the file is a directory */ isDir() { } @@ -38,12 +38,12 @@ class FileInfo { /** * @module fs - * @version 1.0.0 + * @since 1.0.0 */ module.exports = { /** * @description Checks if a file exists - * @version 1.0.0 + * @since 1.0.0 * @param {string} path - Path to the file (for example `/var/www/html/foo.txt`) * @return {boolean} */ @@ -51,7 +51,7 @@ module.exports = { /** * @description Reads the content of a file - * @version 1.0.0 + * @since 1.0.0 * @param {string} path - Path to the file * @return {Bytes} */ @@ -59,7 +59,7 @@ module.exports = { /** * @description Writes data to a file - * @version 1.0.0 + * @since 1.0.0 * @param {string} path - Path to the file * @param {BytesWriter} data - Data as Bytes, e.g. created by `helpers.bytesFromString()` or similar functions * @param {number} mode - File mode bits @@ -69,7 +69,7 @@ module.exports = { /** * @description Returns information about a file - * @version 1.0.0 + * @since 1.0.0 * @param {string} path - Path to the file * @return {FileInfo} FileInfo */ @@ -77,7 +77,7 @@ module.exports = { /** * @description Returns information about all files in a dirictory - * @version 1.0.0 + * @since 1.0.0 * @param {string} path - Path to the directory * @return {FileInfo[]} Array of FileInfo */ @@ -85,7 +85,7 @@ module.exports = { /** * @description Deletes a file or directory - * @version 1.0.0 + * @since 1.0.0 * @param {string} path - Path to the file or directory * @return {boolean} success */ @@ -93,7 +93,7 @@ module.exports = { /** * @description Creates a directory - * @version 1.0.0 + * @since 1.0.0 * @param {string} path - Path of the directory * @return {boolean} success */ @@ -101,7 +101,7 @@ module.exports = { /** * @description Creates every missing directory in a path - * @version 1.0.0 + * @since 1.0.0 * @param {string} path - Path of the directory * @return {boolean} success */ @@ -109,7 +109,7 @@ module.exports = { /** * @description Deletes a file or directory - * @version 1.0.0 + * @since 1.0.0 * @param {string} path - Path to the file or directory * @param {string} newPath - New path to the file or directory * @return {boolean} success diff --git a/api/graphics.js b/api/graphics.js index 885d098..98371f1 100644 --- a/api/graphics.js +++ b/api/graphics.js @@ -1,6 +1,6 @@ /** * @typedef {object} BannerSettings - * @version 0.14.2 + * @since 0.14.2 * @property {string} format - e.g. "png" * @property {number} width * @property {number} height @@ -10,12 +10,12 @@ /** * TODO: Document Layer Parameters! * @typedef {object} BannerLayer - * @version 0.14.2 + * @since 0.14.2 */ /** * @module graphics - * @version 0.14.2 + * @since 0.14.2 * @example * var graphics = require('graphics'); */ diff --git a/api/helpers.js b/api/helpers.js index 1f5376b..52705a3 100644 --- a/api/helpers.js +++ b/api/helpers.js @@ -19,14 +19,14 @@ module.exports = { // TODO: Provide examples how this can be used // /** // * @description Creates a new BytesWriter - // * @version 1.0.0 + // * @since 1.0.0 // * @returns {BytesWriter} // */ // newBytes: () => {}, /** * @description Returns a BytesWriter for a given string - * @version 1.0.0 + * @since 1.0.0 * @param {string} value String * @returns {BytesWriter} */ @@ -34,7 +34,7 @@ module.exports = { /** * @description Returns a BytesWriter for a given hex-string - * @version 1.0.0 + * @since 1.0.0 * @param {string} value Hex-string * @returns {BytesWriter} */ @@ -42,7 +42,7 @@ module.exports = { /** * @description Returns a BytesWriter for a given base64-string - * @version 1.0.0 + * @since 1.0.0 * @param {string} value Base64-string * @returns {BytesWriter} */ diff --git a/api/http.js b/api/http.js index ff98efa..ad17c4c 100644 --- a/api/http.js +++ b/api/http.js @@ -1,7 +1,7 @@ /** * @callback simpleRequestCallback * @see module:http#simpleRequest - * @version 0.14.2 + * @since 0.14.2 * @param {string} [error] * @param {object} [response] * @param {Bytes} response.data - Data; Needs to be converted to a string first, e.g. `response.data.toString()`. @@ -15,7 +15,7 @@ */ module.exports = { /** - * @version 0.14.2 + * @since 0.14.2 * @description Creates an http request * @param {object} config - http configuration object * @param {string} [config.method] - Request Method to use (eg GET, POST, PUT, ...) diff --git a/api/media.js b/api/media.js index 7dc2703..bb102d4 100644 --- a/api/media.js +++ b/api/media.js @@ -60,7 +60,7 @@ module.exports = { * @description Adds the given url as the first entry in the queue * @param {string} url * @returns {boolean} - * @version 0.12.0 + * @since 0.12.0 */ playAsNext: (url) => {}, diff --git a/api/net.js b/api/net.js index 349d110..c338356 100644 --- a/api/net.js +++ b/api/net.js @@ -1,7 +1,7 @@ /** * @interface NetClient - * @version 0.9.16 + * @since 0.9.16 */ class NetClient { /** @@ -43,7 +43,7 @@ class NetClient { /** * @typedef {object} NetConnectParams - * @version 0.9.16 + * @since 0.9.16 * @property {string} [host] - Host to connect to; required for mysql / postgres * @property {number} [port] - Port to use * @property {string} [url] - WebSocket URL to use @@ -53,14 +53,14 @@ class NetClient { /** * @callback netConnectCallback * @see module:net#connect - * @version 0.9.16 + * @since 0.9.16 * @description If an error occured, exactly one parameter containing the error will be handed to the callback. * @param {string} [error] */ /** * @module net - * @version 0.9.16 + * @since 0.9.16 * @example * var net = require('net'); * var engine = require('engine'); diff --git a/api/types.js b/api/types.js index 928607d..ba5caff 100644 --- a/api/types.js +++ b/api/types.js @@ -25,7 +25,7 @@ class ApiEvent { */ remoteAddr() { } /** - * @version 0.14 + * @since 0.14 * @returns {object} Key/Value map of the query parameters in the url */ queryParams() { } @@ -77,7 +77,7 @@ class Client { description() { } /** * @param {string} description - * @version 0.9.19 + * @since 0.9.19 */ setDescription(description) { } /** @@ -292,27 +292,27 @@ class Channel { */ parent() { } /** - * @version 0.9.16.3 + * @since 0.9.16.3 * @returns {number} Order / position of this channel. * For ts3 this is a numeric value determining the order in which channels are displayed below their parent. To set a new value, please use moveTo. */ position() { } /** * @description delete the current channel - * @version 0.9.17 + * @since 0.9.17 * @returns {boolean} */ delete() { } /** * @description Moves the channel to a new parent with a new position value - * @version 0.9.16.3 + * @since 0.9.16.3 * @param {(string|Channel)} parent - New parent channel * @param {number} order - New order value */ moveTo(parent, order) { } /** * @param {string} name - * @version 0.9.16 + * @since 0.9.16 */ setName(name) { } /** @@ -325,17 +325,17 @@ class Channel { topic() { } /** * @param {string} topic - * @version 0.9.16 + * @since 0.9.16 */ setTopic(topic) { } /** - * @version 0.9.19 + * @since 0.9.19 * @returns {string} Description */ description() { } /** * @param {string} description - * @version 0.9.16 + * @since 0.9.16 */ setDescription(description) { } /** @@ -344,7 +344,7 @@ class Channel { codec() { } /** * @param {number} codec - * @version 0.9.16 + * @since 0.9.16 */ setCodec(codec) { } /** @@ -353,7 +353,7 @@ class Channel { codecQuality() { } /** * @param {number} quality - * @version 0.9.16 + * @since 0.9.16 */ setCodecQuality(quality) { } /** @@ -362,7 +362,7 @@ class Channel { maxClients() { } /** * @param {boolean} maxClients Set to -1 for unlimited clients - * @version 0.9.16 + * @since 0.9.16 */ setMaxClients(maxClients) { } /** @@ -371,7 +371,7 @@ class Channel { maxFamilyClients() { } /** * @param {boolean} maxFamilyClients - * @version 0.9.16 + * @since 0.9.16 */ setMaxFamilyClients(maxFamilyClients) { } /** @@ -380,7 +380,7 @@ class Channel { isPermanent() { } /** * @param {boolean} permanent - * @version 0.9.16 + * @since 0.9.16 */ setPermanent(permanent) { } /** @@ -389,7 +389,7 @@ class Channel { isSemiPermanent() { } /** * @param {boolean} permanent - * @version 0.9.16 + * @since 0.9.16 */ setSemiPermanent(permanent) { } /** @@ -406,7 +406,7 @@ class Channel { isEncrypted() { } /** * @param {boolean} encrypted - * @version 0.9.16 + * @since 0.9.16 */ setEncrypted(encrypted) { } /** @@ -435,26 +435,26 @@ class Channel { setSubscription(val) { } /** * @description Updates multiple channel parameters at once - * @version 0.9.16.3 + * @since 0.9.16.3 * @param {ChannelParams} channelParams */ update(channelParams) { } /** * @description Assigns a client to a channel group - * @version 0.9.18 + * @since 0.9.18 * @param {Client} client * @param {ChannelGroup} channelGroup */ setChannelGroup(client, channelGroup) { } /** * @description Gets the permissions for the channel from the server - this is an expensive call as the permissions are _not_ cached - * @version 0.13.37 + * @since 0.13.37 * @returns {Permission[]} */ getPermissions() { } /** * @description Adds/sets a new permission on the channel; you need to use the setters and then call save() to apply - can also be used to remove a permission by delete() afterwards - * @version 0.13.37 + * @since 0.13.37 * @param {string} id - id of the permission to add; can also be supplied as name like i_channel_needed_join_power * @returns {Permission} */ @@ -475,25 +475,25 @@ class ServerGroup { name() { } /** * @returns {string} ID of the icon used for the channel group - * @version 0.12.0 + * @since 0.12.0 */ icon() { } /** * @description Adds a client by database ID to the servergroup * @returns {boolean} status if the request was successful - * @version 0.13.37 + * @since 0.13.37 * @param {(Client|string|number)} client - The client can be a client object, string or number */ addClientByDatabaseId(client) { } /** * @description Gets the permissions for the servergroup from the server - this is an expensive call as the permissions are _not_ cached - * @version 0.13.37 + * @since 0.13.37 * @returns {Permission[]} */ getPermissions() { } /** * @description Adds/sets a new permission to the servergroup; you need to use the setters and then call save() to apply - can also be used to remove a permission by delete() afterwards - * @version 0.13.37 + * @since 0.13.37 * @param {string} id - id of the permission to add; can also be supplied as name like i_channel_needed_join_power * @returns {Permission} */ @@ -514,18 +514,18 @@ class ChannelGroup { name() { } /** * @returns {string} ID of the icon used for the channel group - * @version 0.12.0 + * @since 0.12.0 */ icon() { } /** * @description Gets the permissions for the channelgroup from the server - this is an expensive call as the permissions are _not_ cached - * @version 0.13.37 + * @since 0.13.37 * @returns {Permission[]} */ getPermissions() { } /** * @description Adds/sets a new permission to the channelgroup; you need to use the setters and then call save() to apply - can also be used to remove a permission by delete() afterwards - * @version 0.13.37 + * @since 0.13.37 * @param {string} id - id of the permission to add; can also be supplied as name like i_channel_needed_join_power * @returns {Permission} */ @@ -539,78 +539,78 @@ class User { /** * @description Returns the ID of the user * @returns {string} ID of the User - * @version 0.13.37 + * @since 0.13.37 */ id() { } /** * @description Returns the name of the user * @returns {string} Name of the User - * @version 0.13.37 + * @since 0.13.37 */ name() { } /** * @description Returns the privileges of the user * @returns {number} Privileges of the user - * @version 0.13.37 + * @since 0.13.37 */ privileges() { } /** * @description Returns the teamspeak unique ID of the bind client * @returns {string} teamspeak unique ID of the bind ts client - * @version 0.13.37 + * @since 0.13.37 */ tsUid() { } /** * @description Returns the teamspeak group ID * @returns {string} ID of the bind teamspeak group - * @version 0.13.37 + * @since 0.13.37 */ tsGroupId() { } /** * @description Checks if an user is an admin * @returns {boolean} Admin status of the user - * @version 0.13.37 + * @since 0.13.37 */ isAdmin() { } /** * @description Sets a new password to the user * @returns {boolean} Success or not * @param {string} password - new password of the user - * @version 0.13.37 + * @since 0.13.37 */ setPassword(password) { } /** * @description Sets the teamspeak unique ID to the user * @returns {boolean} Success or not * @param {string} tsUid - teamspeak unique ID of the client - * @version 0.13.37 + * @since 0.13.37 */ setTSUid(tsUid) { } /** * @description Sets the privileges to an user * @returns {boolean} Success or not * @param {number} privileges - New privileges of the user - * @version 0.13.37 + * @since 0.13.37 */ setPrivileges(privileges) { } /** * @description Adds an privilege to an user * @returns {boolean} Success or not * @param {number} privilege - New privilege which should be added - * @version 0.13.37 + * @since 0.13.37 */ addPrivilege(privilege) { } /** * @description Removes an privilege from an user * @returns {boolean} Success or not * @param {number} privilege - Privilege which should be removed - * @version 0.13.37 + * @since 0.13.37 */ removePrivilege(privilege) { } /** * @description Deletes an user * @returns {boolean} Success or not - * @version 0.13.37 + * @since 0.13.37 */ delete() { } } @@ -618,64 +618,64 @@ class User { /** * @interface Permission * @description handles channel, channelgroup and servergroup permissions; mainly for TS3 - * @version 0.13.37 + * @since 0.13.37 */ class Permission { /** - * @version 0.13.37 + * @since 0.13.37 * @returns {string} ID of the permission */ id() { } /** - * @version 0.13.37 + * @since 0.13.37 * @returns {string} Name of the permission */ name() { } /** - * @version 0.13.37 + * @since 0.13.37 * @returns {number} permission value */ value() { } /** - * @version 0.13.37 + * @since 0.13.37 * @returns {boolean} true, if skip flag has been set - only applicable for ServerGroups */ skip() { } /** - * @version 0.13.37 + * @since 0.13.37 * @returns {boolean} true, if negated flag has been set - only applicable for ServerGroups */ negated() { } /** * @description sets the value of the permission; you need to call save() to apply changes - * @version 0.13.37 + * @since 0.13.37 * @param {boolean} value - true, if permission should be negated, false otherwise * @returns {boolean} */ setNegated(value) { } /** * @description sets the skip flag - only applicable for ServerGroups; you need to call save() to apply changes - * @version 0.13.37 + * @since 0.13.37 * @param {boolean} value - true, if permission should be skipped, false otherwise * @returns {boolean} */ setSkip(value) { } /** * @description sets the negated flag - only applicable for ServerGroups; you need to call save() to apply changes - * @version 0.13.37 + * @since 0.13.37 * @param {number} value - new value for the permission * @returns {boolean} */ setValue(value) { } /** * @description applies the changed settings - * @version 0.13.37 + * @since 0.13.37 * @returns {boolean} */ save() { } /** * @description delete the current permission - * @version 0.13.37 + * @since 0.13.37 * @returns {boolean} */ delete() { } @@ -719,17 +719,17 @@ class Track { album() { } /** * @returns {string} Genre of the track - * @version 0.9.16 + * @since 0.9.16 */ genre() { } /** * @returns {number} Duration of the track - * @version 0.9.16 + * @since 0.9.16 */ duration() { } /** * @returns {number} Tracknumber of the track - * @version 0.9.16 + * @since 0.9.16 */ trackNumber() { } /** @@ -829,7 +829,7 @@ class PlaylistTrack { /** * @interface Bytes - * @version 0.9.16 + * @since 0.9.16 */ class Bytes { /** diff --git a/api/ws.js b/api/ws.js index 2ed8912..297ef1c 100644 --- a/api/ws.js +++ b/api/ws.js @@ -1,6 +1,6 @@ /** * @module ws - * @version 0.9.20 + * @since 0.9.20 * @fires event#event:ws.connect * @fires event#event:ws.close * @fires event#event:ws.error From c9e2ba64cad29c7a537c9d97cc6564e355734317 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20B=C3=B6gle?= Date: Thu, 14 Feb 2019 02:43:41 +0100 Subject: [PATCH 03/11] fix: use correct callback in db.exec --- api/db.js | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/api/db.js b/api/db.js index 0e95459..2e8c03f 100644 --- a/api/db.js +++ b/api/db.js @@ -1,4 +1,3 @@ -// TODO: improve parameter documentation /** * @interface DBConn * @since 0.9.16.4 @@ -18,7 +17,7 @@ class DBConn { * @description Use this insted of query if you don't expect a result * @param {string} queryString * @param {any} [parameters] - Zero or more parameters; e.g. for mysql, ? in the queryString will be replaced with these parameters - * @param {function} [callback] + * @param {dbQueryCallback} [callback] */ exec(queryString, parameters, callback) {} } From a995acd7ff4fc1a4eeab6ed3496743ea372a6278 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20B=C3=B6gle?= Date: Thu, 14 Feb 2019 02:44:32 +0100 Subject: [PATCH 04/11] use todo tag --- api/fs.js | 2 +- api/graphics.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api/fs.js b/api/fs.js index c0799f6..7fead07 100644 --- a/api/fs.js +++ b/api/fs.js @@ -13,9 +13,9 @@ class FileInfo { * @returns {string} Length in bytes for regular files; system-dependent for others */ size() { } - // FIXME: Either document FileMode or change to number /** * @since 1.0.0 + * @todo FIXME: Document FileMode or change to number * @returns {FileMode} File mode bits */ mode() { } diff --git a/api/graphics.js b/api/graphics.js index 98371f1..545ce99 100644 --- a/api/graphics.js +++ b/api/graphics.js @@ -8,7 +8,7 @@ */ /** - * TODO: Document Layer Parameters! + * @todo TODO: Document Layer Parameters! * @typedef {object} BannerLayer * @since 0.14.2 */ From e2c50910c956d57b1e774203d265a0e393985ea5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20B=C3=B6gle?= Date: Thu, 14 Feb 2019 02:45:02 +0100 Subject: [PATCH 05/11] update links to new doc --- api/globals.js | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/api/globals.js b/api/globals.js index 62ecf73..05c7e32 100644 --- a/api/globals.js +++ b/api/globals.js @@ -1,5 +1,3 @@ -// TODO: update links - /** * @typedef {object} Manifest * @see registerPlugin @@ -24,10 +22,10 @@ * @param {string[]} [requiredModules] * Using this, you can define which restricted modules the script wants to use. If it's not allowed via the config, the script will not load at all but instead return an error on startup. * If you only optionally use features from restricted modules, don't use this but provide a fallback in your script. - * @param {object[]} [vars] - More information about the usage of variables can be found [here](https://wiki.sinusbot.com/en:guides:features:scripts:variables). + * @param {object[]} [vars] - More information about the usage of variables can be found [here](https://sinusbot.github.io/docs/scripts/#vars-array). * @param {string[]} [voiceCommands] * This parameter is only used for the speech recognition feature and may contain one or more strings that are to be detected for the given script. - * You can find more details on how to use it here: [Speech Recognition](https://wiki.sinusbot.com/en:guides:features:speechrecognition) + * You can find more details on how to use it here: [Speech Recognition](https://sinusbot.github.io/docs/speechrecognition/) */ /** From 44ce6462ccd3ff2219ebf0533e5f880811a74023 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20B=C3=B6gle?= Date: Thu, 14 Feb 2019 03:59:00 +0100 Subject: [PATCH 06/11] fix: optinal parameter --- api/media.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/media.js b/api/media.js index bb102d4..5d32029 100644 --- a/api/media.js +++ b/api/media.js @@ -76,7 +76,7 @@ module.exports = { /** * @description Stops playback completely - * @param {string} trackID - (optional) the track to stop; if not present, all tracks will be stopped + * @param {string} [trackID] - (optional) the track to stop; if not present, all tracks will be stopped * @returns {boolean} */ stop: (trackID) => {}, From 9feb2343f06d1be8f1c9ffd22fb6bd5ae31c6992 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20B=C3=B6gle?= Date: Thu, 14 Feb 2019 05:30:34 +0100 Subject: [PATCH 07/11] es6 -> es2018 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9494401..f8c56e4 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ After you have the typings installed, you need to create a `jsconfig.json` in th ```json { "compilerOptions": { - "target": "es5", // or "es6" if sinusbot version >1.0.0 + "target": "es5", // or "es2018" if sinusbot version >= 1.0.0 "checkJs": true } } From f3cbca50b71ee61d420885ca2c9f3c1eecd73cdf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20B=C3=B6gle?= Date: Tue, 19 Feb 2019 00:36:30 +0100 Subject: [PATCH 08/11] updated setAudioFilter description --- api/audio.js | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/api/audio.js b/api/audio.js index 50a5e4d..fbc897c 100644 --- a/api/audio.js +++ b/api/audio.js @@ -3,9 +3,11 @@ */ module.exports = { /** - * @description Applies an audiofilter to the audio output + * @description Applies a [ffmpeg filter](https://ffmpeg.org/ffmpeg-filters.html) to the audio output. + * + * Warning: This method is curretly **not safe to use** and **leads to crashes**! * @param {string} filter - ffmpeg compatible filter string - * @returns {boolean} + * @returns {boolean} success */ setAudioFilter: (filter) => {}, From 2ffd3ddcbcb461807566af2aaf5c24ee19cae316 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20B=C3=B6gle?= Date: Thu, 21 Feb 2019 20:28:52 +0100 Subject: [PATCH 09/11] update FileInfo.mode() --- api/fs.js | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/api/fs.js b/api/fs.js index 7fead07..1c4012f 100644 --- a/api/fs.js +++ b/api/fs.js @@ -8,32 +8,30 @@ class FileInfo { * @returns {string} Base name of the file */ name() { } + /** * @since 1.0.0 * @returns {string} Length in bytes for regular files; system-dependent for others */ size() { } + /** * @since 1.0.0 - * @todo FIXME: Document FileMode or change to number - * @returns {FileMode} File mode bits + * @returns {number} [File mode bits](https://en.wikipedia.org/wiki/Chmod#Numerical_permissions) */ mode() { } + /** * @since 1.0.0 * @returns {Date} Modification time */ modTime() { } + /** * @since 1.0.0 * @returns {boolean} Returns if the file is a directory */ isDir() { } - // FIXME: What is returned here exactly? - // /** - // * @returns {object} Underlying data source (can return nil) - // */ - // sys() { } } /** From f90c018ae61f847a9f1d18e9bafb85e448db2d1e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20B=C3=B6gle?= Date: Fri, 22 Feb 2019 17:45:16 +0100 Subject: [PATCH 10/11] use new favicon flag instead of sed --- .travis.yml | 3 +-- apply_favicon.sed | 3 --- 2 files changed, 1 insertion(+), 5 deletions(-) delete mode 100644 apply_favicon.sed diff --git a/.travis.yml b/.travis.yml index d2d7e79..4697dc6 100644 --- a/.travis.yml +++ b/.travis.yml @@ -4,9 +4,8 @@ node_js: script: - npm install -g documentation jsdoc - documentation build api/ -c documentation.yml - --project-name "SinusBot Scripting Engine" --project-version " " + --project-name "SinusBot Scripting Engine" --project-version " " --favicon "/favicon.ico" --shallow -f html -o documentation -- sed -f apply_favicon.sed -i documentation/index.html - jsdoc -c config.json || true - cp tsd/types.d.ts documentation deploy: diff --git a/apply_favicon.sed b/apply_favicon.sed deleted file mode 100644 index c5fd6bd..0000000 --- a/apply_favicon.sed +++ /dev/null @@ -1,3 +0,0 @@ -# insert the favicon meta tag before the head closing tag -/<\/head>/i\ - From 79af2f8916a12419e480bc9f28e92b31c1faa84f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20B=C3=B6gle?= Date: Fri, 22 Feb 2019 17:51:53 +0100 Subject: [PATCH 11/11] use tsd-jsdoc from repo, add logfile --- .gitignore | 1 - package-lock.json | 172 ++++++++++++++++++++++++++++++++++++++++++++++ package.json | 2 +- 3 files changed, 173 insertions(+), 2 deletions(-) create mode 100644 package-lock.json diff --git a/.gitignore b/.gitignore index 3e57c75..1034591 100644 --- a/.gitignore +++ b/.gitignore @@ -2,5 +2,4 @@ documentation out node_modules -package-lock.json tsd \ No newline at end of file diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..c83a2d6 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,172 @@ +{ + "name": "sinusbot-scripting-engine", + "version": "1.0.6", + "lockfileVersion": 1, + "requires": true, + "dependencies": { + "babylon": { + "version": "7.0.0-beta.19", + "resolved": "https://registry.npmjs.org/babylon/-/babylon-7.0.0-beta.19.tgz", + "integrity": "sha512-Vg0C9s/REX6/WIXN37UKpv5ZhRi6A4pjHlpkE34+8/a6c2W1Q692n3hmc+SZG5lKRnaExLUbxtJ1SVT+KaCQ/A==", + "dev": true + }, + "bluebird": { + "version": "3.5.1", + "resolved": "https://registry.npmjs.org/bluebird/-/bluebird-3.5.1.tgz", + "integrity": "sha512-MKiLiV+I1AA596t9w1sQJ8jkiSr5+ZKi0WKrYGUn6d1Fx+Ij4tIj+m2WMQSGczs5jZVxV339chE8iwk6F64wjA==", + "dev": true + }, + "catharsis": { + "version": "0.8.9", + "resolved": "https://registry.npmjs.org/catharsis/-/catharsis-0.8.9.tgz", + "integrity": "sha1-mMyJDKZS3S7w5ws3klMQ/56Q/Is=", + "dev": true, + "requires": { + "underscore-contrib": "~0.3.0" + } + }, + "escape-string-regexp": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", + "integrity": "sha1-G2HAViGQqN/2rjuyzwIAyhMLhtQ=", + "dev": true + }, + "graceful-fs": { + "version": "4.1.11", + "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.1.11.tgz", + "integrity": "sha1-Dovf5NHduIVNZOBOp8AOKgJuVlg=", + "dev": true + }, + "js2xmlparser": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/js2xmlparser/-/js2xmlparser-3.0.0.tgz", + "integrity": "sha1-P7YOqgicVED5MZ9RdgzNB+JJlzM=", + "dev": true, + "requires": { + "xmlcreate": "^1.0.1" + } + }, + "jsdoc": { + "version": "3.5.5", + "resolved": "https://registry.npmjs.org/jsdoc/-/jsdoc-3.5.5.tgz", + "integrity": "sha512-6PxB65TAU4WO0Wzyr/4/YhlGovXl0EVYfpKbpSroSj0qBxT4/xod/l40Opkm38dRHRdQgdeY836M0uVnJQG7kg==", + "dev": true, + "requires": { + "babylon": "7.0.0-beta.19", + "bluebird": "~3.5.0", + "catharsis": "~0.8.9", + "escape-string-regexp": "~1.0.5", + "js2xmlparser": "~3.0.0", + "klaw": "~2.0.0", + "marked": "~0.3.6", + "mkdirp": "~0.5.1", + "requizzle": "~0.2.1", + "strip-json-comments": "~2.0.1", + "taffydb": "2.6.2", + "underscore": "~1.8.3" + } + }, + "klaw": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/klaw/-/klaw-2.0.0.tgz", + "integrity": "sha1-WcEo4Nxc5BAgEVEZTuucv4WGUPY=", + "dev": true, + "requires": { + "graceful-fs": "^4.1.9" + } + }, + "marked": { + "version": "0.3.16", + "resolved": "https://registry.npmjs.org/marked/-/marked-0.3.16.tgz", + "integrity": "sha512-diLiAxHidES67uJ1P5unXBUB4CyOFwodKrctuK0U4Ogw865N9Aw4dLmY0BK0tGKOy3xvkdMGgUXPD6W9z1Ne0Q==", + "dev": true + }, + "minimist": { + "version": "0.0.8", + "resolved": "https://registry.npmjs.org/minimist/-/minimist-0.0.8.tgz", + "integrity": "sha1-hX/Kv8M5fSYluCKCYuhqp6ARsF0=", + "dev": true + }, + "mkdirp": { + "version": "0.5.1", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz", + "integrity": "sha1-MAV0OOrGz3+MR2fzhkjWaX11yQM=", + "dev": true, + "requires": { + "minimist": "0.0.8" + } + }, + "requizzle": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/requizzle/-/requizzle-0.2.1.tgz", + "integrity": "sha1-aUPDUwxNmn5G8c3dUcFY/GcM294=", + "dev": true, + "requires": { + "underscore": "~1.6.0" + }, + "dependencies": { + "underscore": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.6.0.tgz", + "integrity": "sha1-izixDKze9jM3uLJOT/htRa6lKag=", + "dev": true + } + } + }, + "strip-json-comments": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz", + "integrity": "sha1-PFMZQukIwml8DsNEhYwobHygpgo=", + "dev": true + }, + "taffydb": { + "version": "2.6.2", + "resolved": "https://registry.npmjs.org/taffydb/-/taffydb-2.6.2.tgz", + "integrity": "sha1-fLy2S1oUG2ou/CxdLGe04VCyomg=", + "dev": true + }, + "tsd-jsdoc": { + "version": "github:englercj/tsd-jsdoc#f5419394f647fc812be12b629c634612ac604c2d", + "from": "github:englercj/tsd-jsdoc", + "dev": true, + "requires": { + "typescript": "^3.2.1" + } + }, + "typescript": { + "version": "3.3.3333", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-3.3.3333.tgz", + "integrity": "sha512-JjSKsAfuHBE/fB2oZ8NxtRTk5iGcg6hkYXMnZ3Wc+b2RSqejEqTaem11mHASMnFilHrax3sLK0GDzcJrekZYLw==", + "dev": true + }, + "underscore": { + "version": "1.8.3", + "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.8.3.tgz", + "integrity": "sha1-Tz+1OxBuYJf8+ctBCfKl6b36UCI=", + "dev": true + }, + "underscore-contrib": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/underscore-contrib/-/underscore-contrib-0.3.0.tgz", + "integrity": "sha1-ZltmwkeD+PorGMn4y7Dix9SMJsc=", + "dev": true, + "requires": { + "underscore": "1.6.0" + }, + "dependencies": { + "underscore": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.6.0.tgz", + "integrity": "sha1-izixDKze9jM3uLJOT/htRa6lKag=", + "dev": true + } + } + }, + "xmlcreate": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/xmlcreate/-/xmlcreate-1.0.2.tgz", + "integrity": "sha1-+mv3YqYKQT+z3Y9LA8WyaSONMI8=", + "dev": true + } + } +} diff --git a/package.json b/package.json index e7ca39b..9b678a1 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,7 @@ "license": "MIT", "devDependencies": { "jsdoc": "^3.5.5", - "tsd-jsdoc": "^2.1.3" + "tsd-jsdoc": "englercj/tsd-jsdoc" }, "typings": "./tsd/types.d.ts" }