irc-time-bot v1.0.0
π€ irc-time-bot β
An IRC Timebot for Freenode πΏ
Description
This project consists of a basic NodeJS prototype for the backend portions of a chatbot that could be called form an IRC channel. For the time being, it only manages these two commands:
!timeat <tzinfo>
: That returns time in the specified timezone.!timepopularity <tzinfo_or_prefix>
: That returns the ammount of valid!timeat
requests that have been received for timezones that start with<tzinfo_or_prefix>
. A βprefixβ is defined as any characters before a/
in atzinfo
string.
To persist popularity data across restarts of the bot application, a simple JSON file is maintained through the app.
In addition, it can be integrated into an actual Freenode IRC server.
Finally, the project is bundled into a simple reusable NPM package to invoke the bot.
π Getting Started
π§ Prerequisites
- NodeJS
- NPM
- Visual Studio Code
- So far, this has been only tested on Windows 10.
π¨βπ» Installing
To get started with the source code, please run the following steps:
Clone repository from GitHub:
Open your terminal and move to your desired folder to contain the project, then execute:
$ git clone https://github.com/MarianoAIglesias1994/irc-time-bot.git
Move into the folder:
$ cd irc-time-bot/
- Run npm install:
$ npm install
πββοΈ Executing
Once you have the previous configuration, you can head into these steps:
- Make sure you have an
.env
file at project root level, with a content like the following example:
## IRC SERVER CONFIG
# IRC Server
IRC_SERVER='chat.freenode.net'
# IRC Server port
IRC_PORT=6667
# Show debug messages
IRC_DEBUG=true
# Secure config
IRC_SECURE=true
# IRC channel name
IRC_CHANNEL=##bot-testing
# Bot nickname
IRC_BOTNICK=TheTimeBot
# TIME API
TIME_API='http://worldtimeapi.org/api/'
TIME_API_ENDPOINT='timezone/'
# STORAGE
STORAGE_FILE='/storage.json'
It contains the different configurations for the bot: IRC server, Time API & Storage. This environment file is ignored by Git, but does not contain any secret so far.
Verify that there is a
storage.json
file undersrc/storage
, with at least an empty array[]
. Here, we will be storing all the requests to the bot, thus, if there's any content you might delete it while erasing this file (β).You are ready to execute the bot, run:
$ npm run start
and it will be up and running in a few seconds.You can connect to the IRC channel you defined in the
.env
file at this web:Please, use a different user name from the bot nickname.
You can start writing messages and monitor them arriving on the bot console, as well as watch how the bot reponds when a certain command is sent. For instance, try out the following commands:
!timeat America/Argentina/Buenos_Aires
!timeat America/Chicago
!timepopularity America
!timepopularity Argentina
!timeat Europe/Berlin
!timeat Europe
You can see that the bot tags the user who issued the command. This is done in order to keep track of who invoked the command in a chatroom with multiple users.
- Particular cases:
- When the
<tzinfo>
of a!timeat
command doesn't match a full timezone, then the bot answers:<username>: Unknown timezone
. This can happen with wrong timezones (v.g.,Nowhere
), or with timezones not specific enough (likeAmerica/Indiana
orEurope
). - When
!timeat Vancouver
is invoked, then the bot responds with the time fromAmerica/Vancouver
instead ofunknown timezone
.
- When the
π¦ Using the bot as an NPM package
This project has been bundled into a simple reusable NPM package to invoke the bot. You may use it by executing $ npm install irc-time-bot
and then you can include in your project like this:
const bot = require("irc-time-bot");
bot.start();
Remember to include the .env
file at project root level.
π Architecture
The app is quite simple, and consists of the following elements:
- The bot manager: that connects to the IRC server, given the configuration, and passes the message parser as the callback for each incoming message.
- The message parser: that filters out the messages only considering those being commands, and invoking the command handler in turn.
The command hanlder: that detects the corresponding command being issued.
In the
!timeat
command, the strategy is to call the Time API, and if it's successful, parse the response fromISO 8601
format to theDD MMM YYYY HH:mm
format and send the answer to the IRC channel. It also accounts the request in the JSON file, implementing a recursive tree structure.In case of any problems with the API, an according response will be sent:
- HTTP Error 404:
<username>: Unknown timezone.
HTTP Error 503:
<username>: Time service unavailable, please try again.
- An special retry policy has been implemented to mitigate these errors.
Every other error:
<username>: Unknown error, please try again.
- HTTP Error 404:
In the
!timepopularity
command, the methodology is to retrieve the account for the particular timezone or prefix from the JSON file in the storage, and then send it back to the command handler and to the IRC channel afterwards.
π Help
In case of any issue don't hesitate to contact me.
β Author
π Version History
- 1.0.0
- Initial Release
3 years ago