https://github.com/ugjka/kittybot
IRCv3 enabled bot for Kittens
https://github.com/ugjka/kittybot
bot bot-framework golang irc ircv3
Last synced: 5 months ago
JSON representation
IRCv3 enabled bot for Kittens
- Host: GitHub
- URL: https://github.com/ugjka/kittybot
- Owner: ugjka
- License: other
- Created: 2020-08-12T14:00:34.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2025-11-22T06:45:31.000Z (7 months ago)
- Last Synced: 2025-11-22T08:27:36.092Z (7 months ago)
- Topics: bot, bot-framework, golang, irc, ircv3
- Language: Go
- Homepage:
- Size: 183 KB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# KittyBot
[](https://godoc.org/github.com/ugjka/kittybot)
A hard fork of [github.com/whyrusleeping/hellabot](https://github.com/whyrusleeping/hellabot)
Kitten approved Internet Relay Chat (IRC) bot. KittyBot is an easily hackable event-based IRC bot
framework with the ability to be updated without losing connection to the
server. To respond to an event, simply create a "Trigger" struct containing
two functions, one for the condition, and one for the action.
## Warning
We are at v0.0.X, the API may change without warning!!!
## Example Trigger
```go
var myTrigger = kitty.Trigger{
Condition: func(bot *kitty.Bot, m *kitty.Message) bool {
return m.From == "ugjka"
},
Action: func(bot *kitty.Bot, m *kitty.Message) {
bot.Reply(m, "ugjka said something")
},
}
```
The trigger makes the bot announce to everyone that something was said in the current channel. Use the code snippet below to make the bot and add the trigger.
```go
bot, err := kitty.NewBot("irc.libera.chat:6697","kittybot")
if err != nil {
panic(err)
}
bot.AddTrigger(MyTrigger)
bot.Run() // Blocks until exit
```
The 'To' field on the message object in triggers will refer to the channel that
a given message is in unless it is a server message or a user-to-user private message. In such cases, the field will be the target user's name.
For more example triggers, check the examples directory.
## The Message struct
The message struct is primarily what you will be dealing with when building
triggers or reading from the Incoming channel.
This is mainly the ircmsg.Message struct with some additions.
See [https://github.com/ugjka/ircmsg/blob/master/message.go#L221](https://github.com/ugjka/ircmsg/blob/master/message.go#L221)
```go
// Message represents a message received from the server
type Message struct {
// ircmsg.Message with extended data, like GetTag() for IRCv3 tags
*ircmsg.Message
// Content generally refers to the text of a PRIVMSG
Content string
// Raw contains the raw message
Raw string
//Time at which this message was recieved
TimeStamp time.Time
// Entity that this message was addressed to (channel or user)
To string
// Nick of the messages sender (equivalent to Prefix.Name)
// Outdated, please use .Name
From string
}
```
## Connection Passing
KittyBot can restart without dropping its connection to the server
(on Linux machines, and BSD flavors) by passing the TCP connection through a UNIX domain socket.
This allows you to update triggers and other addons without actually logging
your bot out of the IRC, avoiding the loss of op status and spamming the channel
with constant join/part messages. To do this, run the program again with
the same nick and without killing the first program (different nicks won't reuse the same bot instance). The first program will shut down, and the new one
will take over.
\***\*This does not work with SSL connections, because we can't hand over a SSL connections state.\*\***
## Security
KittyBot supports both SSL and SASL for secure connections to whichever server
you like. To enable SSL, pass the following option to the NewBot function.
```go
sslOptions := func(bot *kitty.Bot) {
bot.SSL = true
}
bot, err := kitty.NewBot("irc.libera.chat:6697","kittybot",sslOptions)
// Handle err as you like
bot.Run() # Blocks until disconnect.
```
To use SASL to authenticate with the server:
```go
saslOption = func(bot *kitty.Bot) {
bot.SASL = true
bot.Password = "somepassword"
}
bot, err := kitty.NewBot("irc.freenode.net:6667", "kittybot", saslOption)
// Handle err as you like
bot.Run() # Blocks until disconnect.
```
Note: SASL does not require SSL but can be used in combination.
## Passwords
For servers that require passwords in the initial registration, simply set
the Password field of the Bot struct before calling its Start method.
## Debugging
Hellabot uses github.com/inconshreveable/log15 for logging.
See [http://godoc.org/github.com/inconshreveable/log15](http://godoc.org/github.com/inconshreveable/log15)
By default, it discards all logs. To see any logs, give it a better handler.
Example: This would only show INFO level and above logs, logging to STDOUT
```go
import log "gopkg.in/inconshreveable/log15.v2"
logHandler := log.LvlFilterHandler(log.LvlInfo, log.StdoutHandler)
bot.Logger.SetHandler(logHandler)
```
Note: This might be revisited in the future.
## Why
What do you need an IRC bot for you ask? Well, I've gone through the trouble of
compiling a list of fun things for you! The following are some of the things KittyBot is
currently being used for:
- AutoOp Bot: ops you when you join the channel
- Stats counting bot: counts how often people talk in a channel
- Mock users, you don't like by repeating what they say
- Fire a USB dart launcher on a given command
- Control an MPD radio stream based on chat commands
- Award praise to people for guessing a random number
- Scrape news sites for relevant articles and send them to a channel
- And many other 'fun' things!
## References
[Client Protocol, RFC 2812](http://tools.ietf.org/html/rfc2812)
[SASL Authentication Documentation](https://tools.ietf.org/html/draft-mitchell-irc-capabilities-01)
[IRCv3 Documentation](https://ircv3.net/irc/)
## Contributors before the hard fork
- @[sorcix](https://github.com/sorcix)
- @[whyrusleeping](https://github.com/whyrusleeping)
- @[flexd](https://github.com/flexd)
- @[icholy](https://github.com/icholy)
- @[bbriggs](https://github.com/bbriggs)
- @[Luzifer](https://github.com/Luzifer)
- @[mudler](https://github.com/mudler)
- @[jonreyna](https://github.com/jonreyna)
- @[miloprice](https://github.com/miloprice)
- @[m-242](https://github.com/m-242)
- @[antifuchs](https://github.com/antifuchs)
- @[JReyLBC](https://github.com/)
- @[ForrestWeston](https://github.com/ForrestWeston)
- @[affankingkhan](https://github.com/affankingkhan)
- @[Villawhatever](https://github.com/Villawhatever)