From 8edf8fe2d5f222203c357f37f96c38958f2d3f46 Mon Sep 17 00:00:00 2001 From: MiniDigger Date: Sun, 3 Nov 2019 11:37:41 +0100 Subject: [PATCH 1/2] Add documentation for public client --- _api/commands.md | 40 ++++++++++++++++++ _api/public-client.md | 95 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 135 insertions(+) create mode 100644 _api/commands.md create mode 100644 _api/public-client.md diff --git a/_api/commands.md b/_api/commands.md new file mode 100644 index 00000000..4334d4d2 --- /dev/null +++ b/_api/commands.md @@ -0,0 +1,40 @@ +--- +layout: documentation +title: Commands +description: The Command API lets you add new commands. +type: server +--- + +The Command API lets you add new commands. + +```js +const helloWorldCommand = { + input: function (client, target, command, args) { + if(args.length === 0) { + client.sendMessage("Hello World", target.chan); + } else { + client.sendMessage("Hello " + args[0], target.chan); + } + }, + allowDisconnected: true +}; +module.exports = { + onServerStart: api => { + api.Commands.add("helloworld", helloWorldCommand); + }, +}; +``` + +Arguments: + +**`client: PublicClient`** +: The client API + +**`target: Object`** +: `target.network` is the network this command was run in, `target.chan` the corresponding channel. + +**`command: String`** +: The command name (lowercase). + +**`args: Array of String`** +: The arguments the command was executed with. diff --git a/_api/public-client.md b/_api/public-client.md new file mode 100644 index 00000000..c669ed5e --- /dev/null +++ b/_api/public-client.md @@ -0,0 +1,95 @@ +--- +layout: documentation +title: Public Client +description: The Public Client API lets you interact with the client +type: server +--- + +The Public Client API lets you interact with the client + +## Methods + +### `#runAsUser(command: String, targetId: String)` + +Allows to make the client send a message/run a command. + +Arguments: + +**`command: String`** +: IRC command to run, this is in the same format that a client would send to the server (eg: JOIN #test). + +**`targetId: String`** +: The id of the channel to simulate the command coming from. Replies will go to this channel if appropriate + +### `#createChannel(attributes: Object)` + +Allows to create a new channel. + +attributes: +**`id: Number`** +:The id of the channel, defaults to 0. + +**`messages: Array of Msg`** +:The messages of the channel, defaults to empty array. + +**`name: String`** +:The name of the channel, defaults to empty string. + +**`key: String`** +:The key of the channel, defaults to empty string. + +**`topic: String`** +:The topic of the channel, defaults to empty string. + +**`type: Chan.Type`** +:The type of the channel, defaults to `CHANNEL`. Available types: `CHANNEL`, `LOBBY`, `QUERY`, `SPECIAL`. +Special is used for banlist, invitelist, channellist or ignorelist. + +**`state: Chan.State`** +:The state of the channel, defaults to `PARTED`, Possible states: `PARTED`, `JOINED`. + +**`firstUnread: Number`** +:The first unread message, defaults to 0. + +**`unread: Number`** +:The number of unread messages, defaults to 0. + +**`highlight: Number`** +:The number of highlights, defaults to 0. + +**`users: Map from String to User`** +:The users of the channel, key is the lowercase nick, the value is the user object. Defaults to empty map. + +### `#sendToBrowser(event: String, data: Object)` + +Emits an `event` to the browser client, with `data` in the body of the event. + +Arguments: + +**`event: String`** +:Name of the event, must be something the browser will recognise. + +**`data: Object`** +:Body of the event, can be anything, but will need to be properly interpreted by the client. + +### `#getChannel(channelId: Number)` + +Looks up a channel by ID. + +Arguments: + +**`channelId: Number`** +:The id of the channel to return. + +### `#sendMessage(text: String, chan: Chan)` + +Sends a message to this client, displayed in the given channel. +This message will be displayed as a plugin message, the sender will be the name of your plugin (define in your package.json under thelounge.name) and defaults to the package name. + +Arguments: + +**`text: String`** +:The content of the message. + +**`chan: Chan`** +:The channel to send this message into. From b5e194ebca9db379d820ad8aa3e9ad28284e6c89 Mon Sep 17 00:00:00 2001 From: MiniDigger Date: Sun, 3 Nov 2019 11:45:59 +0100 Subject: [PATCH 2/2] Document Command#add + small fixes --- _api/commands.md | 46 +++++++++++++++++++++++++++++-------------- _api/public-client.md | 37 +++++++++++++++++----------------- 2 files changed, 50 insertions(+), 33 deletions(-) diff --git a/_api/commands.md b/_api/commands.md index 4334d4d2..5a270d1d 100644 --- a/_api/commands.md +++ b/_api/commands.md @@ -7,6 +7,36 @@ type: server The Command API lets you add new commands. +## Methods + +### `#add(command: Object)` + +Adds a new command. + +Attributes of command: + +**`input: Function`** +: The implementation of the command, see the arguments below: + +**`allowDisconnected: Boolean`** +: If `true` this command can be execute when the client isn't connected. + +## Arguments of a command: + +**`client: PublicClient`** +: The client API + +**`target: Object`** +: `target.network` is the network this command was run in, `target.chan` the corresponding channel. + +**`command: String`** +: The command name (lowercase). + +**`args: Array of String`** +: The arguments the command was executed with. + +## Example + ```js const helloWorldCommand = { input: function (client, target, command, args) { @@ -23,18 +53,4 @@ module.exports = { api.Commands.add("helloworld", helloWorldCommand); }, }; -``` - -Arguments: - -**`client: PublicClient`** -: The client API - -**`target: Object`** -: `target.network` is the network this command was run in, `target.chan` the corresponding channel. - -**`command: String`** -: The command name (lowercase). - -**`args: Array of String`** -: The arguments the command was executed with. +``` \ No newline at end of file diff --git a/_api/public-client.md b/_api/public-client.md index c669ed5e..7be37437 100644 --- a/_api/public-client.md +++ b/_api/public-client.md @@ -19,46 +19,47 @@ Arguments: : IRC command to run, this is in the same format that a client would send to the server (eg: JOIN #test). **`targetId: String`** -: The id of the channel to simulate the command coming from. Replies will go to this channel if appropriate +: The id of the channel to simulate the command coming from. Replies will go to this channel if appropriate ### `#createChannel(attributes: Object)` Allows to create a new channel. -attributes: +Attributes: + **`id: Number`** -:The id of the channel, defaults to 0. +: The id of the channel, defaults to 0. **`messages: Array of Msg`** -:The messages of the channel, defaults to empty array. +: The messages of the channel, defaults to empty array. **`name: String`** -:The name of the channel, defaults to empty string. +: The name of the channel, defaults to empty string. **`key: String`** -:The key of the channel, defaults to empty string. +: The key of the channel, defaults to empty string. **`topic: String`** -:The topic of the channel, defaults to empty string. +: The topic of the channel, defaults to empty string. **`type: Chan.Type`** -:The type of the channel, defaults to `CHANNEL`. Available types: `CHANNEL`, `LOBBY`, `QUERY`, `SPECIAL`. +: The type of the channel, defaults to `CHANNEL`. Available types: `CHANNEL`, `LOBBY`, `QUERY`, `SPECIAL`. Special is used for banlist, invitelist, channellist or ignorelist. **`state: Chan.State`** -:The state of the channel, defaults to `PARTED`, Possible states: `PARTED`, `JOINED`. +: The state of the channel, defaults to `PARTED`, Possible states: `PARTED`, `JOINED`. **`firstUnread: Number`** -:The first unread message, defaults to 0. +: The first unread message, defaults to 0. **`unread: Number`** -:The number of unread messages, defaults to 0. +: The number of unread messages, defaults to 0. **`highlight: Number`** -:The number of highlights, defaults to 0. +: The number of highlights, defaults to 0. **`users: Map from String to User`** -:The users of the channel, key is the lowercase nick, the value is the user object. Defaults to empty map. +: The users of the channel, key is the lowercase nick, the value is the user object. Defaults to empty map. ### `#sendToBrowser(event: String, data: Object)` @@ -67,10 +68,10 @@ Emits an `event` to the browser client, with `data` in the body of the event. Arguments: **`event: String`** -:Name of the event, must be something the browser will recognise. +: Name of the event, must be something the browser will recognise. **`data: Object`** -:Body of the event, can be anything, but will need to be properly interpreted by the client. +: Body of the event, can be anything, but will need to be properly interpreted by the client. ### `#getChannel(channelId: Number)` @@ -79,7 +80,7 @@ Looks up a channel by ID. Arguments: **`channelId: Number`** -:The id of the channel to return. +: The id of the channel to return. ### `#sendMessage(text: String, chan: Chan)` @@ -89,7 +90,7 @@ This message will be displayed as a plugin message, the sender will be the name Arguments: **`text: String`** -:The content of the message. +: The content of the message. **`chan: Chan`** -:The channel to send this message into. +: The channel to send this message into.