File Coverage

blib/lib/Dubber/API.pm

Criterion	Covered	Total	%
statement	52	166	31.3
branch	0	58	0.0
condition	0	10	0.0
subroutine	26	42	61.9
pod			n/a
total	78	276	28.2

package Dubber::API;

# ABSTRACT: Interact with the Dubber Call Recording platform API

use strict;
use warnings;

our $VERSION = '0.011'; # VERSION
our $AUTHORITY = 'cpan:NIGELM'; # AUTHORITY

use Mouse;
use Method::Signatures;
use Cpanel::JSON::XS;
use Crypt::Digest::MD5 qw[md5_b64];
use Crypt::Digest::SHA256 qw[sha256_hex];
use DateTime;
use HTTP::Request;
use LWP::ConnCache;
use LWP::UserAgent;
use Try::Tiny;
use URI;

with 'Web::API';

# ------------------------------------------------------------------------


# ------------------------------------------------------------------------

has api_version => (
    is      => 'ro',
    isa     => 'Num',
    default => sub {'1'},
);

has region => (
    is      => 'ro',
    isa     => 'Str',
    default => sub {'sandbox'},
);

# ------------------------------------------------------------------------

has client_id       => (is => 'ro', isa=> 'Str', required => 1);
has client_secret   => (is => 'ro', isa=> 'Str', required => 1);
has auth_id         => (is => 'ro', isa=> 'Str', required => 1);
has auth_secret     => (is => 'ro', isa=> 'Str', required => 1);
has max_part_size   => (is => 'ro', isa=> 'Int', default => sub { 5 * 1024 * 1024});
# ------------------------------------------------------------------------
has _auth_token         => (is => 'rw', isa => 'Str', predicate => '_has_auth_token', clearer => 'clear_auth_token',);
has _auth_refresh_token => (is => 'rw', isa => 'Str',);
has _auth_token_expiry  => (is => 'rw', isa => 'DateTime',);

method _new_auth_token ($refresh_token?) {
    my $uri = URI->new( $self->base_url . '/token' );
    my $request = HTTP::Request->new( 'POST', $uri );
    $request->header(
        'Accept'       => 'application/json',
        'Content-type' => 'application/x-www-form-urlencoded'
    );

    # token request content
    my $content = { client_id => $self->client_id, client_secret => $self->client_secret };
    if ($refresh_token) {

        # refresh request content...
        $content->{refresh_token} = $refresh_token;
        $content->{grant_type}    = 'refresh_token';
    }
    else {
        $content->{username}   = $self->auth_id;
        $content->{password}   = $self->auth_secret;
        $content->{grant_type} = 'password';
    }
    $request->content( $self->encode( $content, 'application/x-www-form-urlencoded' ) );

    # send and decode query
    $self->_clear_state;
    my $response = $self->request($request);
    my $answer   = $self->format_response($response);
    $self->_clear_state;

    # unpack components
    $self->_auth_token( $answer->{content}{access_token} );
    $self->_auth_refresh_token( $answer->{content}{refresh_token} );
    $self->_auth_token_expiry( DateTime->now->add( seconds => $answer->{content}{expires_in} - 20 ) );

    # return the token
    return $answer->{content}{access_token};
}

# ------------------------------------------------------------------------
method is_authenticated () {
    return 1 if ( ( $self->_has_auth_token ) and ( DateTime->now < $self->_auth_token_expiry ) );
    return;
}

# ------------------------------------------------------------------------
method auth_token () {
    if ( $self->_has_auth_token ) {
        if ( DateTime->now > $self->_auth_token_expiry ) {
            $self->_new_auth_token( $self->_auth_refresh_token );
        }
    }
    else {
        $self->_new_auth_token();
    }
    return $self->_auth_token;
}

# ------------------------------------------------------------------------
method auth_lifetime_seconds () {
    return 0 unless ( $self->is_authenticated );
    my $diff = $self->_auth_token_expiry->delta_ms( DateTime->now );
    return ( abs( $diff->minutes * 60 ) + abs( $diff->seconds ) );
}

# ------------------------------------------------------------------------
has header => (
    is         => 'rw',
    isa        => 'HashRef',
    lazy_build => 1,
);

method _build_header () {
    return { Authorization => 'Bearer ' . $self->auth_token };
}

# ------------------------------------------------------------------------
has connection_cache => (
    is         => 'ro',
    isa        => 'LWP::ConnCache',
    lazy_build => 1,
);

method _build_connection_cache () { return LWP::ConnCache->new( total_capacity => 5 ); }

# ------------------------------------------------------------------------
has json_coder => (
    is         => 'ro',
    isa        => 'Cpanel::JSON::XS',
    lazy_build => 1,
);

method _build_json_coder () { return Cpanel::JSON::XS->new->utf8; }

# ------------------------------------------------------------------------
has endpoints => (
    is      => 'ro',
    default => sub {
        {   root => { path => '/' },

            # Group Methods (Group Authentication Required)
            get_group_details                 => { path => 'groups/:group_id' },
            get_group_accounts                => { path => 'groups/:group_id/accounts' },
            create_child_group                => { path => 'groups/:group_id/groups', method => 'POST' },
            create_account                    => { path => 'accounts', method => 'POST' },
            get_group_unidentified_recordings => { path => 'groups/:group_id/unidentified_recordings' },
            create_group_unidentified_recording =>
                { path => 'groups/:group_id/unidentified_recordings', method => 'POST' },

            # Account Methods
            get_account_details    => { path => 'accounts/:account_id' },
            update_account_details => { path => 'accounts/:account_id', method => 'PUT' },

            # Recording Methods
            get_account_recordings    => { path => 'accounts/:account_id/recordings',   method => 'GET' },
            create_recording          => { path => 'accounts/:account_id/recordings',   method => 'POST' },
            get_recording_details     => { path => 'recordings/:recording_id',          method => 'GET' },
            get_recording_waveform    => { path => 'recordings/:recording_id/waveform', method => 'GET' },
            delete_recording          => { path => 'recordings/:recording_id',          method => 'DELETE' },
            update_recording_metadata => { path => 'recordings/:recording_id/metadata', method => 'PUT' },
            add_recording_tags        => { path => 'recordings/:recording_id/tags',     method => 'POST' },
            delete_recording_tags     => { path => 'recordings/:recording_id/tags',     method => 'DELETE' },

            # Multipart Recording Methods
            create_multipart_recording => { path => 'accounts/:account_id/recordings', method => 'POST' },
            get_recording_upload_part  => {
                path   => 'recordings/:recording_id/upload',
                method => 'GET',

                #mandatory => [qw(part_number content_md5 content_sha256)]
            },
            put_complete_multipart_recording_upload =>

                #{ path => 'recordings/:recording_id/complete_upload', method => 'PUT', mandatory => [qw(parts)] },
                { path => 'recordings/:recording_id/complete_upload', method => 'PUT', },
            abort_multipart_recording_upload => { path => 'recordings/:recording_id', method => 'DELETE' },

            # User Methods
            get_account_users   => { path => 'accounts/:account_id/users', method => 'GET' },
            create_account_user => { path => 'accounts/:account_id/users', method => 'POST' },
            get_user_details    => { path => 'users/:user_id',             method => 'GET' },
            delete_user         => { path => 'users/:user_id',             method => 'DELETE' },
            update_user         => { path => 'users/:user_id',             method => 'PUT' },

            # Profile Methods
            get_profile => { path => 'profile', method => 'GET' },

            # Notification (Rest Hook) Methods
            create_group_notification => { path => 'groups/:group_id/notifications', method => 'POST' }
            ,    # (Group Authentication Only)
            get_group_notifications => { path => 'groups/:group_id/notifications', method => 'GET' }
            ,    # (Group Authentication Only)
            create_account_notification    => { path => 'accounts/:account_id/notifications',       method => 'POST' },
            get_account_notifications      => { path => 'accounts/:account_id/notifications',       method => 'GET' },
            get_notification_details       => { path => 'notifications/:notification_id',           method => 'GET' },
            update_notification            => { path => 'notifications/:notification_id',           method => 'PUT' },
            activate_notification          => { path => 'notifications/:notification_id/activate',  method => 'POST' },
            release_unclaimed_notification => { path => 'notifications/:notification_id/unclaimed', method => 'GET' },
            delete_notification => { path => 'notifications/:notification_id', method => 'DELETE' },

            # Dub.Point (Group Authentication Required)
            get_group_unidentified_dub_points =>
                { path => 'groups/:group_id/unidentified_dub_points', method => 'GET' },
            get_account_dub_points   => { path => 'accounts/:account_id/dub_points', method => 'GET' },
            create_account_dub_point => { path => 'accounts/:account_id/dub_points', method => 'POST' },
            get_dub_point_details    => { path => 'dub_points/:dub_point_id',        method => 'GET' },
            find_dub_point           => {
                path      => 'dub_points/find',
                method    => 'GET',
                mandatory => [qw(external_type service_provider external_group external_identifier)]
            },

            # OAuth 2 Methods
            revoke_access_token => { path => 'revoke', method => 'POST' },

        };
    },
);

method commands () { return $self->endpoints; }

# ------------------------------------------------------------------------
method upload_recording_mp3_file ($account_id, $call_metadata, $mp3_file_or_data) {
    my @data_parts = $self->_split_recording_data($mp3_file_or_data);

    # create the recording object
    my $res = $self->create_recording( account_id => $account_id, %{$call_metadata} );
    if ( $res->{code} eq '201' ) {
        my $recording_id = $res->{content}{id};
        my $return_status;
        try {
            my @etag_parts;
            my $part_number = 0;
            foreach my $part_data (@data_parts) {
                my $md5_b64    = md5_b64($part_data);
                my $sha256_hex = sha256_hex($part_data);
                ++$part_number;

                # request to upload a recording part
                my $upload_req_res = $self->get_recording_upload_part(
                    recording_id   => $recording_id,
                    part_number    => $part_number,
                    content_md5    => $md5_b64,
                    content_sha256 => $sha256_hex
                );
                if ( $upload_req_res->{code} eq '200' ) {

                    # upload the recording part
                    my $put_uri = URI->new( $upload_req_res->{content}{url} );
                    my $put_request = HTTP::Request->new( 'PUT', $put_uri );
                    $put_request->header(
                        'Accept'               => 'application/json',
                        'Content-type'         => 'audio/mpeg',                                # apparently right!
                        'Authorization'        => $upload_req_res->{content}{authorization},
                        'X-Amz-Date'           => $upload_req_res->{content}{'X-Amz-Date'},
                        'Host'                 => $upload_req_res->{content}{Host},
                        'Content-Md5'          => $md5_b64,
                        'X-Amz-Content-Sha256' => $sha256_hex
                    );
                    $put_request->content($part_data);
                    my $put_response = $self->request($put_request);
                    if ( $put_response->is_success ) {
                        push( @etag_parts, { part_number => $part_number, e_tag => $put_response->header('ETag') } );
                    }
                    else {
                        die "Unable to PUT recording upload - $!";
                    }
                }
                else {
                    die "Unable to request recording upload - $!";
                }
            }
            $return_status = $self->put_complete_multipart_recording_upload(
                recording_id => $recording_id,
                parts        => \@etag_parts
            );
        }
        catch {
            # it failed - delete the part uploaded chunk
            $self->abort_multipart_recording_upload( recording_id => $recording_id );
        };
        return $return_status;
    }
    return $res;
}

# ------------------------------------------------------------------------
method _split_recording_data ($file_or_data) {
    my $data;
    if ( ref($file_or_data) and $file_or_data->isa('Path::Tiny') ) {
        my $stat = $file_or_data->stat or die "File $file_or_data does not exist - $!\n";
        $data = $file_or_data->slurp_raw;
    }
    else {
        $data = $file_or_data;
    }

    # split into chunks of $max_part_size
    my $template =
        sprintf( 'A%d', $self->max_part_size ) x int( length($data) / $self->max_part_size )
        . ( length($data) % $self->max_part_size )
        ? 'A*'
        : '';
    my @chunks = unpack( $template, $data );
    return @chunks;
}

# ------------------------------------------------------------------------
method BUILD ($args) {
    $self->user_agent( __PACKAGE__ . ' ' . ( $Dubber::API::VERSION || '' ) );
    $self->base_url( 'https://api.dubber.net/' . $self->region . '/v' . $self->api_version );
    $self->content_type('application/json');
    $self->decoder( sub { $self->json_coder->decode( shift || '{}' ) } );
}

# ------------------------------------------------------------------------
method _build_agent () {
    return LWP::UserAgent->new(
        agent      => $self->user_agent,
        cookie_jar => $self->cookies,
        timeout    => $self->timeout,
        con_cache  => $self->connection_cache,
        keep_alive => 1,
        ssl_opts   => { verify_hostname => $self->strict_ssl },
    );
}

# ------------------------------------------------------------------------
method _clear_state () { $self->clear_decoded_response; $self->clear_response; }

# ------------------------------------------------------------------------

__PACKAGE__->meta->make_immutable;

1;

__END__

=pod

=encoding UTF-8

=head1 NAME

Dubber::API - Interact with the Dubber Call Recording platform API

=head1 VERSION

version 0.011

This is undocumented to an amazing degree at present!

=head1 AUTHOR

Nigel Metheringham <[e-mail]>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Nigel Metheringham.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut