view release on metacpan or  search on metacpan

lib/Google/RestApi/GmailApi1.pm  view on Meta::CPAN

package Google::RestApi::GmailApi1;

our $VERSION = '2.2.3';

use Google::RestApi::Setup;

use Encode qw(encode);
use MIME::Base64 qw(encode_base64);
use MIME::Lite;
use Readonly;
use URI;

use aliased 'Google::RestApi::GmailApi1::Message';
use aliased 'Google::RestApi::GmailApi1::Thread';
use aliased 'Google::RestApi::GmailApi1::Draft';
use aliased 'Google::RestApi::GmailApi1::Label';

Readonly our $Gmail_Endpoint => 'https://gmail.googleapis.com/gmail/v1/users';

sub new {
  my $class = shift;
  state $check = signature(
    bless => !!0,
    named => [
      api      => HasApi,
      user_id  => Str, { default => 'me' },
      endpoint => Str, { default => $Gmail_Endpoint },
    ],
  );
  return bless $check->(@_), $class;
}

sub api {
  my $self = shift;
  state $check = signature(
    bless => !!0,
    named => [
      uri     => Str, { optional => 1 },
      _extra_ => slurpy HashRef,
    ],
  );
  my $p = named_extra($check->(@_));
  my $uri = "$self->{endpoint}/$self->{user_id}/";
  $uri .= delete $p->{uri} if defined $p->{uri};
  return $self->{api}->api(%$p, uri => $uri);
}

sub message {
  my $self = shift;
  state $check = signature(
    bless => !!0,
    named => [
      id => Str, { optional => 1 },
    ],
  );
  my $p = $check->(@_);
  return Message->new(gmail_api => $self, %$p);
}

sub thread {
  my $self = shift;
  state $check = signature(
    bless => !!0,
    named => [
      id => Str, { optional => 1 },
    ],
  );
  my $p = $check->(@_);
  return Thread->new(gmail_api => $self, %$p);
}

sub draft {
  my $self = shift;
  state $check = signature(
    bless => !!0,
    named => [
      id => Str, { optional => 1 },
    ],
  );
  my $p = $check->(@_);
  return Draft->new(gmail_api => $self, %$p);
}

sub label {
  my $self = shift;
  state $check = signature(
    bless => !!0,
    named => [
      id => Str, { optional => 1 },
    ],
  );
  my $p = $check->(@_);
  return Label->new(gmail_api => $self, %$p);
}

sub profile {
  my $self = shift;
  return $self->api(uri => 'profile');
}

sub messages {
  my $self = shift;
  state $check = signature(

lib/Google/RestApi/GmailApi1.pm  view on Meta::CPAN

=item * Label management (create, get, update, delete)

=item * Batch operations (batch modify/delete messages)

=item * Attachment retrieval

=back

It is assumed that you are familiar with the Google Gmail API:
L<https://developers.google.com/gmail/api/reference/rest>

=head2 Architecture

The API uses a hierarchical object model where child objects delegate API calls
to their parent:

 GmailApi1 (top-level)
   |-- message(id => ...)       -> Message
   |     |-- attachment(id => ...) -> Attachment
   |-- thread(id => ...)        -> Thread
   |-- draft(id => ...)         -> Draft
   |-- label(id => ...)         -> Label

Each object provides CRUD operations appropriate to its resource type.

=head1 NAVIGATION

=over

=item * L<Google::RestApi::GmailApi1> - This module (top-level Gmail API)

=item * L<Google::RestApi::GmailApi1::Message> - Message operations

=item * L<Google::RestApi::GmailApi1::Attachment> - Attachment retrieval

=item * L<Google::RestApi::GmailApi1::Thread> - Thread management

=item * L<Google::RestApi::GmailApi1::Draft> - Draft management

=item * L<Google::RestApi::GmailApi1::Label> - Label management

=back

=head1 SUBROUTINES

=head2 new(%args)

Creates a new GmailApi1 instance.

 my $gmail_api = Google::RestApi::GmailApi1->new(api => $rest_api);

%args consists of:

=over

=item * C<api> L<Google::RestApi>: Required. A configured RestApi instance.

=item * C<user_id> <string>: Optional. The user ID (default 'me' for authenticated user).

=item * C<endpoint> <string>: Optional. Override the default Gmail API endpoint.

=back

=head2 api(%args)

Low-level method to make API calls. You would not normally call this directly
unless making a Google API call not currently supported by this framework.

%args consists of:

=over

=item * C<uri> <string>: Path segments to append to the Gmail endpoint.

=item * C<%args>: Additional arguments passed to L<Google::RestApi>'s api() (content, params, method, etc).

=back

Returns the response hash from the Google API.

=head2 message(%args)

Returns a Message object for the given message ID.

 my $msg = $gmail_api->message(id => 'msg_id');

=head2 thread(%args)

Returns a Thread object for the given thread ID.

 my $thread = $gmail_api->thread(id => 'thread_id');

=head2 draft(%args)

Returns a Draft object for the given draft ID.

 my $draft = $gmail_api->draft(id => 'draft_id');

=head2 label(%args)

Returns a Label object for the given label ID.

 my $label = $gmail_api->label(id => 'label_id');

=head2 profile()

Gets the authenticated user's Gmail profile.

 my $profile = $gmail_api->profile();

Returns a hashref with emailAddress, messagesTotal, threadsTotal, historyId.

=head2 messages(%args)

Lists messages in the user's mailbox.

 my @messages = $gmail_api->messages();
 my @filtered = $gmail_api->messages(params => { q => 'from:user@example.com' });
 my @paged = $gmail_api->messages(max_pages => 2, params => { maxResults => 10 });

%args consists of:

=over

=item * C<max_pages> <int>: Optional. Maximum number of pages to fetch (default 1). Set to 0 for unlimited.

=item * C<page_callback> <coderef>: Optional. See L<Google::RestApi/PAGE CALLBACKS>.

=item * C<params> <hashref>: Optional. Query parameters (q, maxResults, labelIds, etc).

=back

Returns a list of message hashrefs with id and threadId.