NAME

Bot::BasicBot::Pluggable::Module::Notify - runs a IRC offline notification service

DESCRIPTION

When you have been away from IRC for more than 15 minutes, and someone posts a message mentioning you, this module will detect this, and send you a short email notification, detailing the sendee, the message, the channel and the time sent.

In addition to specific user mentions, the abillity to send to @here (active in the last hour, but not in the last 15 minutes) or @all (all connected users, but not active in the last 15 minutes)

These latter two special cases are shortcuts to enable urgent or group wide messages to reach their intended recipients.

Only users which have email addresses in the notification configuration file are alerted.

If a user leaves the channel within the minimum activity period (defaul 15 minutes), and they are explicitly mentioned in the message, they are also notified.

SYNOPSIS

    my $bot = Bot::BasicBot::Pluggable->new(
        ... # various settings
    }; 

    $bot->store->set( 'notify', 'notifications', '/path/to/my/configuration.csv' },
    $bot->load('Seen');     # must be loaded to use Noify effectively
    $bot->load('Notify');

METHODS

told()

Loads the email notification file, if not previously done so, and checks whether a channel user, @here or @all has been used. Sends the email to all a ppropriately listed email recipients.

Note that a change to the notification file, will force a reload of the file on the next invocation. As such, note that there may be a delay before you see the next updated entry actioned.

Please also note that we try to avoid 'seen' and 'karma' requests, but the odd one may slip through.

VARS

'notifications'

Path to the notification file.

The notification file is assumed to be either based on the calling script, or a designated file. If based on the calling script, if your script was mybot.pl, the notification file would default to mybot.csv.

If you wish to designate another filename or path, you may do this via the variable storage when the bot is initiated. For example:

    my $bot = Bot::BasicBot::Pluggable->new(
        ... # various settings
    }; 

    $bot->store->set( 'notify', 'notifications', '/path/to/my/configuration.csv' },
 

CONFIGURATION FILE

The notifications file is a comma separated file, with blank lines and lines beginnning with a '#' symbol ignored.

Each line in the file should consist of 3 fields. The first being the 'nick', the second being the ident of the account connection, and the third being the email address to send mail to.

The connection ident is optional, and only used as a backup check in the event that the user may be roaming and their nick may be automatically switched to something like '_barbie' instead of 'barbie'. An connection ident is used within a regex pattern, but should not be a regex itself. Any regex characters will be treated as literal string characters.

An example file might look like:

  barbie,missbarbell,barbie@cpan.org
  someone,,someone@example.com

Becareful using the ident, as this may pick up unwanted messages for other similarly named users.

In addition to the emails, there are several Email sending configuration lines. Some optional, others are mandatory. These are designated using the 'CONFIG' key. These are:

  CONFIG,smtp,smtp.example.com
  CONFIG,replyto,no-reply@example.com
  CONFIG,from,no-reply@example.com

A value for 'smtp' is mandatory, while the others are optional.

TODO

• enable / disable notifications

  A user should be able to enable or disable notifications for themselves. This would require a writeable config file, so that this can be stored permanently.

  Should also look at enabling / disabling notifications on a per channel basis.

• user attributed email

  A user should be able to add themselves to the notification list.

• user specified time default

  Should be able to allow a user to set their own active wait time.

AUTHOR

  Barbie, <barbie@cpan.org>
  for Miss Barbell Productions <http://www.missbarbell.co.uk>.

COPYRIGHT AND LICENSE

  Copyright (C) 2015 Barbie for Miss Barbell Productions

  This distribution is free software; you can redistribute it and/or
  modify it under the Artistic License v2.