File Coverage

blib/lib/WebService/Async/Segment/Customer.pm

Criterion	Covered	Total	%
statement	51	51	100.0
branch	26	28	92.8
condition	5	10	50.0
subroutine	12	12	100.0
pod	7	7	100.0
total	101	108	93.5

package WebService::Async::Segment::Customer;

use strict;
use warnings;

use constant COMMON_FIELDS => qw(context integrations timestamp);

our $VERSION = '0.001';    # VERSION

=head1 NAME

WebService::Async::Segment::Customer - represents a customer object with methods to make Segment API calls.

=head1 DESCRIPTION

You can create objects directly or (preferably) indirectly using C<< WebService::Async::Segment::new_customer >>.
Segment calls L and L can be triggered on objects of this class.

=cut

=head1 METHODS

=head2 new

Class constructor accepting a hash of named args containing customer info, along with a Segment API wrapper object (an object of class L).
There is no need to make this call if you create an object using C<< WebService::Async::Segment::new_customer >> (as recommended).

The accepted params are:

=over 4

=item * C - Segment API wrapper object.

=item * C or C - Unique identifier of a user.

=item * C or C - A pseudo-unique substitute for a User ID, for cases when you don't have an absolutely unique identifier.

=item * C - Free-form dictionary of traits of the user, like email or name.

=back

=cut

sub new {
    my ($class, %args) = @_;

    die 'Missing required arg api_client' unless $args{api_client};
    my $api_client = $args{api_client};
    die 'Invalid api_client value' unless $api_client->isa('WebService::Async::Segment');

    my $self;

    $args{user_id}      = delete $args{userId}      if $args{userId};
    $args{anonymous_id} = delete $args{anonymousId} if $args{anonymousId};

    $self->{$_} = $args{$_} for (qw(api_client user_id anonymous_id));
    $self->{traits} = {%{$args{traits}}} if $args{traits};

    bless $self, $class;

    return $self;
}

=head2 user_id

Unique identifier for the user in the database.

=cut

sub user_id { shift->{user_id} }

=head2 anonymous_id

A pseudo-unique substitute for a User ID, for cases when you don't have an absolutely unique identifier.

=cut

sub anonymous_id { shift->{anonymous_id} }

=head2 traits

Free-form dictionary of traits of the user, containg both standard and custom attributes.
For more information on standard (reserved) traits please refer to L.

=cut

sub traits { shift->{traits} }

=head2 api_client

A C object acting as Segment HTTP API client.

=cut

sub api_client { shift->{api_client} }

=head2 identify

Makes an B call on the current customer.
For a detailed information on the API call please refer to: L.

It can be called with the following named params:

=over

=item * C or C - Unique identifier of a user (will overwrite object's attribute).

=item * C or C - A pseudo-unique substitute for a User ID (will overwrite object's attribute).

=item * C - Free-form dictionary of traits of the user, like email or name (will overwrite object's attribute).

=item * C - Context information of the API call.
Note that the API wrapper automatically sets context B and B fields.

=item * C -  Dictionary of destinations to either enable or disable.

=item * C - Timestamp when the message itself took place, defaulted to the current time by the Segment Tracking API. It is an ISO-8601 date string

=item * C - Dictionary of custom business specific fileds.

=back

About common fields please refer to: L.

It returns a L object.

=cut

sub identify {
    my ($self, %args) = @_;

    $args{traits} //= $self->traits if $self->traits;

    $args{user_id}      = delete $args{userId}      if $args{userId};
    $args{anonymous_id} = delete $args{anonymousId} if $args{anonymousId};

    my %call_args = $self->_make_call_args(\%args, [COMMON_FIELDS, qw(user_id anonymous_id traits)]);

    return $self->api_client->method_call('identify', %call_args)->then(
        sub {
            for (qw(user_id anonymous_id)) {
                $self->{$_} = $args{$_} if $args{$_};
            }
            $self->{traits} = {%{$args{traits}}} if $args{traits};

            return Future->done(@_);
        })->retain;
}

=head2 track

Makes a B call on the current customer. It can take any standard (B and B), common or custom fields.
For more information on track API please refer to L.

It can be called with the following parameters:

=over

=item * C - required. event name.

=item * C - Free-form dictionary of event properties.

=item * C - Context information of the API call.
Note that the API wrapper automatically sets context B and B fields.

=item * C -  Dictionary of destinations to either enable or disable.

=item * C - Timestamp when the message itself took place, defaulted to the current time by the Segment Tracking API. It is an ISO-8601 date string.

=item * C - Dictionary of custom business specific fileds.

=back

About common API call params: L.

It returns a L object.

=cut

sub track {
    my ($self, %args) = @_;

    return Future->fail('ValidationError', 'segment', 'Missing required argument "event"') unless $args{event};

    my %call_args = $self->_make_call_args(\%args, [COMMON_FIELDS, qw(event properties)]);

    return $self->api_client->method_call('track', %call_args);
}

sub _make_call_args {
    my ($self, $args, $accepted_fields) = @_;
    $args //= {};
    my $custom = delete $args->{custom} // {};

    for my $field (keys %$args) {
        delete $args->{$field} unless grep { $field eq $_ } (@$accepted_fields);
    }

    for (qw(user_id anonymous_id)) {
        $args->{$_} //= $self->$_ if $self->$_;
    }

    my %call_args = map { $args->{$_} ? ($_ => $args->{$_}) : () } (keys %$args);

    return (%$custom, %call_args);
}

1;

__END__