package JWebmail::Model::ReadMails::Role;

use Params::Check 'check';

use Mojo::Base -role; # load after imports


sub Auth {
    shift;
    state $AuthCheck = {
        user => {required => 1, defined => 1},
        password => {required => 1, defined => 1},
        challenge => {defined => 1},
    };
    my $self = @_ == 1 ? {$_[0]} : {@_};

    return check($AuthCheck, $self, 1) || die;
}

requires(
    # name:type  parmeter of type
    # *key       key => value
    # key=value  default argument of value
    # ^          throws exception
    # ^type      throws exception of type
    # Read operations
    'verify_user',      # auth:Auth -> :truthy
    'read_headers_for', # auth:Auth, *folder='', *start=0, *end=24, *sort='date' -> ^ :hashref
    'count',            # auth:Auth, folder -> ^ size:int count:int new:int
    'show',             # auth:Auth, mid -> ^ :hashref
    'search',           # auth:Auth, pattern, folder -> ^ :hashref
    'folders',          # auth:Auth -> ^ :arrayref
    # Write operations
    'move',             # auth:Auth, mid, folder -> ^ 1
);

around read_headers_for => sub {
    my $orig = shift;
    my $self = shift;
    my $auth = shift;
    my $args = {@_};

    state $ArgsCheck = {
        start =>  {default => 0},
        end =>    {default => 24},
        sort =>   {default => 'date'},
        folder => {default => ''},
    };

    $orig->($self, $auth, %{ check($ArgsCheck, $args, 1) })
};


1

__END__

=encoding utf-8

=head1 NAME

ReadMails::Role - Interface to a repository of mails

=head1 SYNOPSIS

    my $m = Some::Implementation->with_role('JWebmail::Model::ReadMails::Role');
    $m->search($auth, qr/Hot singles in your area/, '');

=head1 DESCRIPTION

The communication is assumed to be stateless.

=head1 INTERFACE

=head2 verify_user

Checks user name and password.

=head2 read_headers_for

Provides bundeled information on a subset of mails of a mailbox.
Can be sorted and of varying size.

Arguments:
    start..end   inclusive 0 based range

=head2 count

Returns size of the mail box folder in bytes the number of mails.

=head2 show

Returns a sepecific mail as a perl hash.

=head2 search

Searches for a message with the given pattern.

=head2 folders

List all mailbox sub folders.

=head2 move

Move mails between folders.

=head2 Auth

A sub that returns a hashref of bundled authentication data.

=head3 Attributes

=head4 user

The user name.

=head4 password

The users password in plaintext or as hmac if cram is used.

=head4 challenge

Optinal challange for when you use cram authentication.

=head1 SEE ALSO

L<JWebmail::Model::ReadMails::QMailAuthuser>, L<JWebmail::Model::ReadMails::Mock>, L<JWebmail>

=cut