=pod

=encoding utf8

=head1 NAME

Bot::ChatBots::Telegram::Role::Source - Telegram Source Role

=head1 SYNOPSIS

   package Some::Thing;
   use Moo;
   with 'Bot::ChatBots::Telegram::Role::Source';
   ...

=head1 DESCRIPTION

This role is meant to be consumed by L<Bot::ChatBots::Telegram::WebHook>
and L<Bot::ChatBots::Telegram::LongPoll>.

=head1 ACCESSORS

This role defines the accessors in the following subsections.

=head2 B<< sender >>

   my $sender = $obj->sender;
   $obj->sender(Bot::ChatBots::Telegram::Sender->new(token => $token));

Accessor for the L<Bot::ChatBots::Telegram::Sender> object useful for
managing communications to Telegram.

=head2 B<< token >>

   my $token = $obj->token;
   $obj->token($ENV{TOKEN});

Accessor for the token, used to access the Telegram service remotely. This
also has an associated predicate function L</has_token>.

=head1 METHODS

This method defines the methods in the following subsections.

=head2 B<< has_token >>

   say 'yes!' if $obj->has_token;

Predicate function to assess whether a L</token> is present or not.

=head2 B<< normalize_record >>

   my $record = $self->normlize_record($input_record);

Perform some normalization on the record to give it a more "general"
shape. Which is still in a state of flux, so a look to the code might
be helpful.

So far you should find the following keys in the returned record:

=over

=item C<chan>

optional element containing data about the Chat where the Update
came from. It is present when C<data_type> is either C<Message> or
C<CallbackQuery> and absent otherwise.

In the C<Message> case, it is the expansion of the C<chat> part of the
C<payload>.

In the C<CallbackQuery> case, it can be:

=over

=item *

the expansion of the C<chat> part inside the C<message> part of the 
Update data, if C<message> is present (Telegram documentation states
this field is optional in the API), otherwise

=item *

a simple anonymous hash where the C<id> field is filled with the
C<chat_instance> field from the payload. Whether this is meaningful
or not is debatable.

=back

=item C<data_type>

the Telegram type for the data pointed to by the optional field. For
example, if the optional field in the Update is C<edited_message>, then
C<data_type> will be C<Message>. See
L<https://core.telegram.org/bots/api#update> for the mapping between
C<type> and C<data_type>.

=item C<payload>

the actual optional object pointed to by C<type>. For example, if
C<type> is C<message>, then C<payload> will point to a hash with the
contents explained at
L<https://core.telegram.org/bots/api#message>.

=item C<sender>

whatever is contained in the C<from> field of the C<payload>

=item C<source>

points to a hash containing the C<technology> (set to C<telegram>) and
C<token> (either inherited, or set to whatever value is pointed by key
C<object_token> in C<source> itself)

=item C<type>

the field name of the optional part in a Telegram's Update, see
L<https://core.telegram.org/bots/api#update> (e.g. C<message>,
C<edited_message> and so on).

=back

=head1 SEE ALSO

L<Bot::ChatBots>.

=head1 AUTHOR

Flavio Poletti <polettix@cpan.org>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2016, 2018 by Flavio Poletti <polettix@cpan.org>

This module is free software. You can redistribute it and/or modify it
under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but
without any warranty; without even the implied warranty of
merchantability or fitness for a particular purpose.

=cut
