Version 0.12 Release

#4
drill perltidy and POD Cleanup

Author: pscott-au

README.txt

@@ -4,30 +4,47 @@ NAME
 
 VERSION
 
-    version 0.11
+    version 0.12
 
 SYNOPSIS
 
     Access Google API Services Version 1 using an OAUTH2 User Agent
 
-        ## use goauth CLI helper to create the OATH credentials file ( see perldoc goauth )
-    
         use WebService::GoogleAPI::Client;
-        use Data::Dumper;
 
-        my $gapi = WebService::GoogleAPI::Client->new(debug => 0); # my $gapi = WebService::GoogleAPI::Client->new(access_token => '');
-        my $user = '[email protected]'; # full gmail or G-Suite email
+        ## assumes gapi.json configuration in working directory with scoped project and user authorization
+        
+        my $gapi_client = WebService::GoogleAPI::Client->new( debug => 1, gapi_json => './gapi.json', user=> '[email protected]' );
+
+ AUTOMATIC API REQUEST CONSTRUCTION - SEND EMAL
+
+        ## using dotted API Endpoint id to invoke helper validation and default value interpolations etc to send email to self
+        use Email::Simple;    ## RFC2822 formatted messages
+        use MIME::Base64;
+        my $my_email_address = '[email protected]'
+    
 
-        $gapi->auth_storage->setup({type => 'jsonfile', path => './gapi.json' }); # by default
+        my $raw_email_payload = encode_base64( Email::Simple->create( header => [To => $my_email_address, 
+                                                                                 From => $my_email_address, 
+                                                                                 Subject =>"Test email from '$my_email_address' ",], 
+                                                                                 body => "This is the body of email to '$my_email_address'", 
+                                                                    )->as_string 
+                                            );
 
-        $gapi->user($user);       ## allows to select user configuration by google auth'd email address
-        $gapi->do_autorefresh(1); ## refresh auth token with refresh token if auth session has expired
+        $gapi_client->api_query( 
+                                api_endpoint_id => 'gmail.users.messages.send',
+                                options    => { raw => $raw_email_payload },
+                            );
 
- OAUTH CREDENTIALS FILE TO ACCESS SERVCICES
+ MANUAL API REQUEST CONSTRUCTION - GET CALENDAR LIST
 
-    TODO
+        ## Completely manually constructed API End-Point Request to obtain Perl Data Structure converted from JSON response.
+        my $res = $gapi_client->api_query(
+          method => 'get',
+          path => 'https://www.googleapis.com/calendar/users/me/calendarList',
+        )->json;
 
- BUILD
+ new
 
     WebService::GoogleAPI::Client->new( user => '[email protected]',
     gapi_json => '/fullpath/gapi.json' );
@@ -125,30 +142,7 @@ SYNOPSIS
 
     DELEGATED FROM WebService::GoogleAPI::Client::Discovery
 
-FUNCTIONAL CLASS PROPERTIES
-
- ua
-
-    Is a WebService::GoogleAPI::Client::UserAgent
-
-  DELEGATE METHOD
-
-METHODS DELEGATED TO PROPERTY CLASS INSTANCES
-
- access_token ua handles: access_token auth_storage do_autorefresh
- get_scopes_as_array user
-
-    discovery handles: discover_all
-    extract_method_discovery_detail_from_api_spec
-    get_api_discovery_for_api_id get_method_meta
-
-KEY FEATURES
-
-    Aim is to streamline endpoint access without forcing an additional
-    opinionated abstraction layer that imposes unecessary congnitive load.
-    Users of the module should be able to access all Google Services and
-    either use helper features or fully construct requests in a way that is
-    as portable to alternative approaches as possible.
+FEATURES
 
     API Discovery with local caching using CHI File
 
@@ -166,36 +160,6 @@ KEY FEATURES
     configuration, sccoping, authorization and obtaining access_ and
     refresh_ tokensn from users
 
- TODO:
-
-    Refactor AuthStorage and Credentials modules - include capability to
-    handle service accounts credentials which are not currently supported.
-    See https://gist.github.com/gsainio/6322375
-
-    standardise terminology in documentation and code
-
-    include POD for delegated methods
-
-    basic CLI to query API Discovery data ( Potentially with OPEN/Swagger
-    Output option ) potenitlaly evolving to something similar to gcloud
-
-SEE ALSO
-
-      * "/cloud.google.com/apis/docs/cloud-client-libraries" in Google
-      Cloud Client Libraries https:
-
-      * "/www.blog.google/products/google-cloud/" in Google Cloud Blog
-      https:
-
-      * Moo::Google - The original code base later forked into
-      WebService::Google::Client by Steve Dondley. Some shadows of the
-      original design remain
-
-      * "/github.com/APIs-guru/google-discovery-to-swagger" in Google
-      Swagger API https:
-
-      * OAuth2::Client::Google - Perl 6 OAuth2 Client
-
 AUTHOR
 
     Peter Scott <[email protected]>

bin/goauth

@@ -1,9 +1,11 @@
 #!perl
 
-use strict; use warnings; ## required because I can't work out how to get percritic to use my modern config
+use strict;
+use warnings;    ## required because I can't work out how to get percritic to use my modern config
+
 package goauth;
 
-# ABSTRACT: CLI tool with mini http server for negotiating Google OAuth2 Authorisation access tokens that allow offline access to Google API Services on behalf of the user. 
+# ABSTRACT: CLI tool with mini http server for negotiating Google OAuth2 Authorisation access tokens that allow offline access to Google API Services on behalf of the user.
 
 =pod
 
@@ -90,9 +92,9 @@ else
 if ( -e $filename )
 {
   say "File $filename exists";
-  input_if_not_exists( ['gapi/client_id', 'gapi/client_secret', 'gapi/scopes'] ); ## this potentially allows mreging with a json file with data external
-                                                                                  ## to the app or to augment missing scope from file generated from 
-                                                                                  ##  earlier versions of goauth from other libs
+  input_if_not_exists( ['gapi/client_id', 'gapi/client_secret', 'gapi/scopes'] );    ## this potentially allows mreging with a json file with data external
+  ## to the app or to augment missing scope from file generated from
+  ##  earlier versions of goauth from other libs
   runserver();
 }
 else
@@ -114,7 +116,8 @@ sub setup
 
   $oauth->{ client_secret } = _stdin() || croak( 'client secret is required and has no default' );
 
-  print 'scopes ( space sep list - see https://developers.google.com/identity/protocols/googlescopes ): default is - email profile https://www.googleapis.com/auth/plus.profile.emails.read '
+  print
+    'scopes ( space sep list - see https://developers.google.com/identity/protocols/googlescopes ): default is - email profile https://www.googleapis.com/auth/plus.profile.emails.read '
     . "https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/contacts.readonly https://mail.google.com\n";
 
   $oauth->{ scopes } = _stdin();    ## no croak because empty string is allowed an will evoke defaults
@@ -175,7 +178,7 @@ sub runserver
       key           => $config->get( 'gapi/client_id' ),                                    # $config->{gapi}{client_id},
       secret        => $config->get( 'gapi/client_secret' ),                                #$config->{gapi}{client_secret},
       authorize_url => 'https://accounts.google.com/o/oauth2/v2/auth?response_type=code',
-      token_url     => 'https://www.googleapis.com/oauth2/v4/token' ## NB Google credentials.json specifies "https://www.googleapis.com/oauth2/v3/token" 
+      token_url     => 'https://www.googleapis.com/oauth2/v4/token'                         ## NB Google credentials.json specifies "https://www.googleapis.com/oauth2/v3/token"
     }
   };
 
@@ -205,14 +208,14 @@ sub runserver
     my $tokens;
     app->log->info( "Will store tokens in " . $config->getFilename( $config->pathToFile ) );
 
-    if ( $c->param( 'code' ) ) ## postback from google 
+    if ( $c->param( 'code' ) )    ## postback from google
     {
       app->log->info( "Authorization code was retrieved: " . $c->param( 'code' ) );
       $tokens = $c->get_new_tokens( $c->param( 'code' ) );
       app->log->info( "App got new tokens: " . Dumper $tokens);
       if ( $tokens )
       {
-        
+
         if ( $tokens->{ id_token } )
         {
           # my $jwt = Mojo::JWT->new(claims => $tokens->{id_token});
@@ -223,10 +226,10 @@ sub runserver
           # carp "Decode header :".Dumper $header;
 
           $user_data = decode_jwt( token => $tokens->{ id_token }, kid_keys => $c->ua->get( 'https://www.googleapis.com/oauth2/v3/certs' )->res->json, );
+
           #carp "Decoded user data:" . Dumper $user_data;
         }
 
-        
 
         #$user_data->{email};
         #$user_data->{family_name}
@@ -238,22 +241,23 @@ sub runserver
         {
           $config->addToHash( 'gapi/tokens/' . $user_data->{ email }, 'refresh_token', $tokens->{ refresh_token } );
         }
-        else ## with access_type=offline set we should receive a refresh token unless user already has an active one.
+        else    ## with access_type=offline set we should receive a refresh token unless user already has an active one.
         {
           ## carp('Google JWT Did not incude a refresh token - when the access token expires services will become inaccessible');
         }
       }
+
       #$c->render( json => $config->get( 'gapi' ) );
       $c->{ access_token } = $tokens->{ access_token };
-      $c->{user_email} = $user_data->{email};
-      $c->render( template => 'oauth_granted');
+      $c->{ user_email }   = $user_data->{ email };
+      $c->render( template => 'oauth_granted' );
     }
-    else ## PRESENT USER DEFAULT PAGE TO REQUEST GOOGLE AUTH'D ACCESS TO SERVICES
+    else        ## PRESENT USER DEFAULT PAGE TO REQUEST GOOGLE AUTH'D ACCESS TO SERVICES
     {
       $c->render( template => 'oauth' );
     }
   };
-  app->secrets( ['putyourownsecretcookieseedhereforsecurity' . time] ); ## NB persistence cookies not required beyond server run
+  app->secrets( ['putyourownsecretcookieseedhereforsecurity' . time] );    ## NB persistence cookies not required beyond server run
   app->start( 'daemon', '-l', "http://*:$port" );
   return 1;
 }
@@ -275,7 +279,6 @@ sub _stdin
 }
 
 
-
 =head2 TODO: Improve user interface of the HTML templates beneath DATA section
 
 =over 1

dist.ini

@@ -3,7 +3,7 @@ author = Peter Scott <[email protected]>
 license = Apache_2_0
 copyright_holder = Peter Scott and others
 copyright_year = 2017-2018
-version = 0.11
+version = 0.12
 main_module = lib/WebService/GoogleAPI/Client.pm
 
 [PruneCruft]