--- trunk/Nos.pm	2005/05/24 17:04:01	50
+++ trunk/Nos.pm	2005/06/22 16:42:06	63
@@ -16,7 +16,7 @@
 our @EXPORT = qw( 
 );
 
-our $VERSION = '0.4';
+our $VERSION = '0.5';
 
 use Class::DBI::Loader;
 use Email::Valid;
@@ -26,6 +26,7 @@
 use Email::Simple;
 use Email::Address;
 use Mail::DeliveryStatus::BounceParser;
+use Class::DBI::AbstractSearch;
 
 
 =head1 NAME
@@ -39,7 +40,39 @@
 
 =head1 DESCRIPTION
 
-Core module for notice sender's functionality.
+Notice sender is mail handler. It is not MTA, since it doesn't know how to
+receive e-mails or send them directly to other hosts. It is not mail list
+manager because it requires programming to add list members and send
+messages. You can think of it as mechanisam for off-loading your e-mail
+sending to remote server using SOAP service.
+
+It's concept is based around B<lists>. Each list can have zero or more
+B<members>. Each list can have zero or more B<messages>.
+
+Here comes a twist: each outgoing message will have unique e-mail generated,
+so Notice Sender will be able to link received replies (or bounces) with
+outgoing messages.
+
+It doesn't do much more than that. It B<can't> create MIME encoded e-mail,
+send attachments, handle 8-bit characters in headers (which have to be
+encoded) or anything else.
+
+It will just queue your e-mail message to particular list (sending it to
+possibly remote Notice Sender SOAP server just once), send it out at
+reasonable rate (so that it doesn't flood your e-mail infrastructure) and
+track replies.
+
+It is best used to send smaller number of messages to more-or-less fixed
+list of recipients while allowing individual responses to be examined.
+Tipical use include replacing php e-mail sending code with SOAP call to
+Notice Sender. It does support additional C<ext_id> field for each member
+which can be used to track some unique identifier from remote system for
+particular user.
+
+It comes with command-line utility C<sender.pl> which can be used to perform
+all available operation from scripts (see C<perldoc sender.pl>).
+This command is also useful for debugging while writing client SOAP
+application.
 
 =head1 METHODS
 
@@ -74,7 +107,7 @@
 		user		=> $self->{'user'},
 		password	=> $self->{'passwd'},
 		namespace	=> "Nos",
-#		additional_classes      => qw/Class::DBI::AbstractSearch/,
+		additional_classes      => qw/Class::DBI::AbstractSearch/,
 #		additional_base_classes => qw/My::Stuff/,
 		relationships	=> 1,
 	) || croak "can't init Class::DBI::Loader";
@@ -98,7 +131,7 @@
 
 Returns ID of newly created list.
 
-Calls internally L<_add_list>, see details there.
+Calls internally C<_add_list>, see details there.
 
 =cut
 
@@ -108,7 +141,10 @@
 	my $arg = {@_};
 
 	confess "need list name" unless ($arg->{'list'});
-	confess "need list email" unless ($arg->{'list'});
+	confess "need list email" unless ($arg->{'email'});
+
+	$arg->{'list'} = lc($arg->{'list'});
+	$arg->{'email'} = lc($arg->{'email'});
 
 	my $l = $self->_get_list($arg->{'list'}) ||
 		$self->_add_list( @_ ) ||
@@ -118,6 +154,37 @@
 }
 
 
+=head2 delete_list
+
+Delete list from database.
+
+ my $ok = delete_list(
+ 	list => 'My list'
+ );
+
+Returns false if list doesn't exist.
+
+=cut
+
+sub delete_list {
+	my $self = shift;
+
+	my $args = {@_};
+
+	croak "need list to delete" unless ($args->{'list'});
+
+	$args->{'list'} = lc($args->{'list'});
+
+	my $lists = $self->{'loader'}->find_class('lists');
+
+	my $this_list = $lists->search( name => $args->{'list'} )->first || return;
+
+	$this_list->delete || croak "can't delete list\n";
+
+	return $lists->dbi_commit || croak "can't commit";
+}
+
+
 =head2 add_member_to_list
 
 Add new member to list
@@ -126,9 +193,10 @@
  	list => "My list",
 	email => "john.doe@example.com",
 	name => "John A. Doe",
+	ext_id => 42,
  );
 
-C<name> parametar is optional.
+C<name> and C<ext_id> parametars are optional.
 
 Return member ID if user is added.
 
@@ -139,9 +207,10 @@
 
 	my $arg = {@_};
 
-	my $email = $arg->{'email'} || croak "can't add user without e-mail";
+	my $email = lc($arg->{'email'}) || croak "can't add user without e-mail";
 	my $name = $arg->{'name'} || '';
-	my $list_name = $arg->{'list'} || croak "need list name";
+	my $list_name = lc($arg->{'list'}) || croak "need list name";
+	my $ext_id = $arg->{'ext_id'};
 
 	my $list = $self->_get_list($list_name) || croak "list $list_name doesn't exist";
 
@@ -164,6 +233,11 @@
 		$this_user->update;
 	}
 
+	if (defined($ext_id) && ($this_user->ext_id || '') ne $ext_id) {
+		$this_user->ext_id($ext_id);
+		$this_user->update;
+	}
+
 	my $user_on_list = $user_list->find_or_create({
 		user_id => $this_user->id,
 		list_id => $list->id,
@@ -191,7 +265,8 @@
 	email => 'dpavlin@rot13.org
  }
 
-If list is not found, returns false.
+If list is not found, returns false. If there is C<ext_id> in user data,
+it will also be returned.
 
 =cut
 
@@ -200,7 +275,7 @@
 
 	my $args = {@_};
 
-	my $list_name = $args->{'list'} || confess "need list name";
+	my $list_name = lc($args->{'list'}) || confess "need list name";
 
 	my $lists = $self->{'loader'}->find_class('lists');
 	my $user_list = $self->{'loader'}->find_class('user_list');
@@ -215,6 +290,9 @@
 			email => $user_on_list->user_id->email,
 		};
 
+		my $ext_id = $user_on_list->user_id->ext_id;
+		$row->{'ext_id'} = $ext_id if (defined($ext_id));
+
 		push @results, $row;
 	}
 
@@ -237,6 +315,9 @@
 
 Returns false if user doesn't exist.
 
+This function will delete member from all lists (by cascading delete), so it
+shouldn't be used lightly.
+
 =cut
 
 sub delete_member {
@@ -246,6 +327,8 @@
 
 	croak "need name or email of user to delete" unless ($args->{'name'} || $args->{'email'});
 
+	$args->{'email'} = lc($args->{'email'}) if ($args->{'email'});
+
 	my $key = 'name';
 	$key = 'email' if ($args->{'email'});
 
@@ -258,6 +341,46 @@
 	return $users->dbi_commit || croak "can't commit";
 }
 
+=head2 delete_member_from_list
+
+Delete member from particular list.
+
+ my $ok = delete_member_from_list(
+ 	list => 'My list',
+ 	email => 'dpavlin@rot13.org',
+ );
+
+Returns false if user doesn't exist on that particular list.
+
+It will die if list or user doesn't exist. You have been warned (you might
+want to eval this functon to prevent it from croaking).
+
+=cut
+
+sub delete_member_from_list {
+	my $self = shift;
+
+	my $args = {@_};
+
+	croak "need list name and email of user to delete" unless ($args->{'list'} && $args->{'email'});
+
+	$args->{'list'} = lc($args->{'list'});
+	$args->{'email'} = lc($args->{'email'});
+
+	my $user = $self->{'loader'}->find_class('users');
+	my $list = $self->{'loader'}->find_class('lists');
+	my $user_list = $self->{'loader'}->find_class('user_list');
+
+	my $this_user = $user->search( email => $args->{'email'} )->first || croak "can't find user: ".$args->{'email'};
+	my $this_list = $list->search( name => $args->{'list'} )->first || croak "can't find list: ".$args->{'list'};
+
+	my $this_user_list = $user_list->search_where( list_id => $this_list->id, user_id => $this_user->id )->first || return;
+
+	$this_user_list->delete || croak "can't delete user from list\n";
+
+	return $user_list->dbi_commit || croak "can't commit";
+}
+
 =head2 add_message_to_list
 
 Adds message to one list's queue for later sending.
@@ -283,7 +406,7 @@
 
 	my $args = {@_};
 
-	my $list_name = $args->{'list'} || confess "need list name";
+	my $list_name = lc($args->{'list'}) || confess "need list name";
 	my $message_text = $args->{'message'} || croak "need message";
 
 	my $m = Email::Simple->new($message_text) || croak "can't parse message";
@@ -352,7 +475,7 @@
 
 	my $arg = {@_};
 
-	my $list_name = $arg->{'list'} || '';
+	my $list_name = lc($arg->{'list'}) || '';
 	my $driver = $arg->{'driver'} || '';
 	my $sleep = $arg->{'sleep'};
 	$sleep ||= 3 unless defined($sleep);
@@ -363,8 +486,9 @@
 	if (lc($driver) eq 'smtp') {
 		$email_send_driver = 'Email::Send::SMTP';
 		@email_send_options = ['127.0.0.1'];
+	} else {
+		warn "dumping all messages to STDERR\n";
 	}
-	warn "using $driver [$email_send_driver]\n";
 
 	my $lists = $self->{'loader'}->find_class('lists');
 	my $queue = $self->{'loader'}->find_class('queue');
@@ -457,6 +581,8 @@
 	message => $message,
  );
 
+This method is used by C<sender.pl> when receiving e-mail messages.
+
 =cut
 
 sub inbox_message {
@@ -467,6 +593,8 @@
 	return unless ($arg->{'message'});
 	croak "need list name" unless ($arg->{'list'});
 
+	$arg->{'list'} = lc($arg->{'list'});
+
 	my $this_list = $self->_get_list($arg->{'list'}) || croak "can't find list ".$arg->{'list'}."\n";
 
 	my $m = Email::Simple->new($arg->{'message'}) || croak "can't parse message";
@@ -484,7 +612,7 @@
 	my $hash;
 
 	foreach my $a (@addrs) {
-		if ($a->address =~ m/\+([a-f0-9]{$hl})@/) {
+		if ($a->address =~ m/\+([a-f0-9]{$hl})@/i) {
 			$hash = $1;
 			last;
 		}
@@ -508,7 +636,7 @@
 		my $users = $self->{'loader'}->find_class('users');
 		my $from = $m->header('From');
 		$from = $1 if ($from =~ m/<(.*)>/);
-		my $this_user = $users->search( email => $from )->first;
+		my $this_user = $users->search( email => lc($from) )->first;
 		$user_id = $this_user->id if ($this_user);
 	}
 
@@ -569,8 +697,8 @@
 
 	my $arg = {@_};
 
-	my $name = $arg->{'list'} || confess "can't add list without name";
-	my $email = $arg->{'email'} || confess "can't add list without e-mail";
+	my $name = lc($arg->{'list'}) || confess "can't add list without name";
+	my $email = lc($arg->{'email'}) || confess "can't add list without e-mail";
 	my $from_addr = $arg->{'from'};
 
 	my $lists = $self->{'loader'}->find_class('lists');
@@ -611,7 +739,7 @@
 
 	my $lists = $self->{'loader'}->find_class('lists') || confess "can't find lists class";
 
-	return $lists->search({ name => $name })->first;
+	return $lists->search({ name => lc($name) })->first;
 }
 
 ###
@@ -653,6 +781,7 @@
 
  $message_id = NewList(
 	list => 'My list',
+	from => 'Name of my list',
 	email => 'my-list@example.com'
  ); 
 
@@ -663,7 +792,7 @@
 
 	if ($_[0] !~ m/^HASH/) {
 		return $nos->new_list(
-			list => $_[0], email => $_[1],
+			list => $_[0], from => $_[1], email => $_[2],
 		);
 	} else {
 		return $nos->new_list( %{ shift @_ } );
@@ -671,12 +800,33 @@
 }
 
 
+=head2 DeleteList
+
+ $ok = DeleteList(
+	list => 'My list',
+ ); 
+
+=cut
+
+sub DeleteList {
+	my $self = shift;
+
+	if ($_[0] !~ m/^HASH/) {
+		return $nos->delete_list(
+			list => $_[0],
+		);
+	} else {
+		return $nos->delete_list( %{ shift @_ } );
+	}
+}
+
 =head2 AddMemberToList
 
  $member_id = AddMemberToList(
 	list => 'My list',
 	email => 'e-mail@example.com',
-	name => 'Full Name'
+	name => 'Full Name',
+	ext_id => 42,
  );
 
 =cut
@@ -686,7 +836,7 @@
 
 	if ($_[0] !~ m/^HASH/) {
 		return $nos->add_member_to_list(
-			list => $_[0], email => $_[1], name => $_[2],
+			list => $_[0], email => $_[1], name => $_[2], ext_id => $_[4],
 		);
 	} else {
 		return $nos->add_member_to_list( %{ shift @_ } );
@@ -702,6 +852,10 @@
 
 Returns array of hashes with user informations, see C<list_members>.
 
+Returning arrays from SOAP calls is somewhat fuzzy (at least to me). It
+seems that SOAP::Lite client thinks that it has array with one element which
+is array of hashes with data.
+
 =cut
 
 sub ListMembers {
@@ -715,9 +869,32 @@
 		$list_name = $_[0]->{'list'};
 	}
 
-	return $nos->list_members( list => $list_name );
+	return [ $nos->list_members( list => $list_name ) ];
 }
 
+
+=head2 DeleteMemberFromList
+
+ $member_id = DeleteMemberFromList(
+	list => 'My list',
+	email => 'e-mail@example.com',
+ );
+
+=cut
+
+sub DeleteMemberFromList {
+	my $self = shift;
+
+	if ($_[0] !~ m/^HASH/) {
+		return $nos->delete_member_from_list(
+			list => $_[0], email => $_[1],
+		);
+	} else {
+		return $nos->delete_member_from_list( %{ shift @_ } );
+	}
+}
+
+
 =head2 AddMessageToList
 
  $message_id = AddMessageToList(