hunterrock-twitchbot/README.md

Easily create chat bots for Twitch.tv

# hunterrock-twitchbot
Easily create chat bots for Twitch.tv

## Install
Install via NPM
```
$ npm install hunterrock-twitchbot
```

## Example
```javascript
const TwitchBot = require('hunterrock-twitchbot')

const Bot = new TwitchBot({
  username: 'Twitch_Bot',
  oauth: 'oauth:xxxxxxxxxxxxxxxxxxxxxxxxxx',
  channels: ['twitch']
})

Bot.on('join', channel => {
  console.log(`Joined channel: ${channel}`)
})

Bot.on('error', err => {
  console.log(err)
})

Bot.on('message', chatter => {
  if(chatter.message === '!test') {
    Bot.say('Command executed! PogChamp')
  }
})

```

## Index
- [Events](https://github.com/hunterrockmedya/twitchbot#events)
  - [`connected`](https://github.com/hunterrockmedya/twitchbot#connected---)
  - [`join`](https://github.com/hunterrockmedya/twitchbot#join---)
  - [`part`](https://github.com/hunterrockmedya/twitchbot#part---)
  - [`message`](https://github.com/hunterrockmedya/twitchbot#message---chatter-object)
  - [`timeout`](https://github.com/hunterrockmedya/twitchbot#timeout---event-object)
  - [`subscription`](https://github.com/hunterrockmedya/twitchbot#subscription---event-object)
  - [`ban`](https://github.com/hunterrockmedya/twitchbot#ban---event-object)
  - [`error`](https://github.com/hunterrockmedya/twitchbot#error---err-object)
  - [`close`](https://github.com/hunterrockmedya/twitchbot#close---)
- [Methods](https://github.com/hunterrockmedya/twitchbot#methods)
  - [`join()`](https://github.com/hunterrockmedya/twitchbot#join-channelname--string))
  - [`part()`](https://github.com/hunterrockmedya/twitchbot#part-channelname--string)  
  - [`say()`](https://github.com/hunterrockmedya/twitchbot#saymessage-string-err-callback)
  - [`timeout()`](https://github.com/hunterrockmedya/twitchbot#timeoutusername-string-duration-int-reason-string)
  - [`ban()`](https://github.com/hunterrockmedya/twitchbot#banusername-string-reason-string)
  - [`close()`](https://github.com/hunterrockmedya/twitchbot#close)
- [Tests](https://github.com/hunterrockmedya/twitchbot#running-tests)

## Events
### `connected - ()`
This event is emitted when the bot has connected to the IRC server.
#### Usage
```javascript
Bot.on('connected', () => ... )
```

### `join - ()`
This event is emitted when a channel has been joined successfully.
#### Usage
```javascript
Bot.on('join', channel => ... )
```

### `part - ()`
This event is emitted when a channel has been left successfully.
#### Usage
```javascript
Bot.on('part', channel => ... )
```


### `message - (chatter: Object)`
Emitted when a `PRIVSMSG` event is sent over IRC. Chatter object attributes can be found on the [Twitch developers site](https://dev.twitch.tv/docs/v5/guides/irc/#privmsg-twitch-tags)

#### Usage
```javascript
Bot.on('message', chatter => ... )
```


### `timeout - (event: Object)`
Emitted when a user is timed out in the chat. The `ban_reason` attribute is `null` when no reason message is used.

#### Chat Trigger
```javascript
hunterrock_: "/timeout {user} {duration} {reason}"
```

#### Usage
```javascript
Bot.on('timeout', event => ... )
```

### `subscription - (event: Object)`
Emitted when a user subscribes to a channel and chooses to share the subscription in chat.

#### Usage
```javascript
Bot.on('subscription', event => ... )
```

### `ban - (event: Object)`
Emitted when a user is permanently banned from the chat. The `ban_reason` attribute is `null` when no reason message is used.

#### Usage
```javascript
Bot.on('ban', event => ... )
```

#### Chat Trigger
```javascript
hunterrock_: "/ban {user} {reason}"
```


### `error - (err: Object)`
Emitted when any errors occurs in the Twitch IRC channel, or when attempting to connect to a channel.

#### Error types
##### `Login authentication failed`
This error occurs when either your twitch username or oauth are incorrect/invalid.

Response:
```javscript
{ message: 'Login authentication failed' }
```

##### `Improperly formatted auth`
This error occurs when your oauth password is not formatted correctly. The valid format should be `"oauth:your-oauth-password-123"`.

Response:
```javscript
{ message: 'Improperly formatted auth' }
```

##### `Your message was not sent because you are sending messages too quickly`
This error occurs when a message fails to send due to sending messages too quickly. You can avoid this by making the bot a moderator in the channel, if applicable/allowed.

Response:
```javascript
{ message: 'Your message was not sent because you are sending messages too quickly' }
```

#### Usage
```javascript
Bot.on('error', err => ... )
```

#### Example Response
```javascript
{ message: 'Some error happened in the IRC channel' }
```

### `close - ()`
This event is emitted when the irc connection is destroyed via the `Bot.close()` method.
#### Usage
```javascript
Bot.on('close', () => {
  console.log('closed bot irc connection')
})
```

## Methods
### `join(channel: String)`
Attempts to join a channel. If successful, emits the 'join' event.

#### Example
```javascript
Bot.on('join', channel => {
  console.log(`Bot joined ${channel}`)
})
Bot.join('channel2')
```

### `part(channel: String)`
Attempts to part from a channel. If successful, emits the 'part' event.

#### Example
```javascript
Bot.on('part', channel => {
  console.log(`Bot left ${channel}`)
})
Bot.part('channel2')
```

### `say(message: String, channel: []Channel, err: Callback)`
Send a message in the currently connected Twitch channel. `channels` parameter not needed when connected to a single channel. An optional callback is provided for validating if the message was sent correctly.

#### Example
```javascript
Bot.say('This is a message')

Bot.say('Pretend this message is over 500 characters', err => {
  sent: false,
  message: 'Exceeded PRIVMSG character limit (500)'
  ts: '2020-08-13T18:36:54.989Z'
})

Bot.say('message to #channel1', 'channel1')
Bot.say('message to #channel2', 'channel2')
```

### `timeout(username: String, channel: []Channel, duration: int, reason: String)`
Timeout a user from the chat. `channels` parameter not needed when connected to a single channel. Default `duration` is 600 seconds. Optional `reason` message.

#### Example
```javascript
Bot.timeout('hunterrock_', 10)

Bot.timeout('hunterrock_', 5, 'Using a banned word')

Bot.on('message', chatter => {
  if(chatter.message === 'xD') Bot.timeout(chatter.username, 10)
})
```

### `ban(username: String, reason: String)`
Permanently ban a user from the chat. `channels` parameter not needed when connected to a single channel. Optional `reason` message.

#### Example
```javascript
Bot.ban('hunterrock_')

Bot.timeout('hunterrock_', 'Using a banned word')

Bot.on('message', chatter => {
  if(chatter.message === 'Ban me!') Bot.ban(chatter.username)
})
```

### `close()`
Closes the Twitch irc connection. Bot will be removed from the Twitch channel AND the irc server.

#### Example
```javascript
Bot.close()
```

## Running Tests
Running the test suite requires at least two twitch accounts, one moderator account and one normal account. The channel used must be the same - This is so timeout/ban methods can be tested with the mod account. Using these two accounts, set the following environment variables:
```javascript
TWITCHBOT_USERNAME=mod_username
TWITCHBOT_OAUTH=oauth:mod-oauth-token
TWITCHBOT_CHANNEL=mod_channel
TWITCHBOT_USERNAME_NON_MOD=non_mod_username
TWITCHBOT_OAUTH_NON_MOD=oauth:non-mod-oauth-token
TWITCHBOT_CHANNEL_NON_MOD=mod_channel
```
To run the tests (powered with [Mocha](https://mochajs.org/)), use the following command:
```bash
yarn test
```