File Coverage

blib/lib/WebService/Xential.pm

Criterion	Covered	Total	%
statement	71	95	74.7
branch	10	30	33.3
condition			n/a
subroutine	16	21	76.1
pod	9	10	90.0
total	106	156	67.9

package WebService::Xential;
our $VERSION = '0.004';
use v5.26;
use Object::Pad;

# ABSTRACT: A Xential REST API module

class WebService::Xential;
use Carp qw(croak);
use OpenAPI::Client;
use Try::Tiny;
use Mojo::Content::Single;
use Mojo::Asset::Memory;
use JSON::XS qw(encode_json);
use Types::Serialiser qw();

field $api_key :param;
field $api_user :param;
field $api_host :param :accessor;
field $api_port :param = undef;
field $api_path :param = '/xential/modpages/next.oas/api';
field $client :accessor;


ADJUST {

    my $definition = sprintf('data://%s/xential.json', ref $self);

    $client = OpenAPI::Client->new($definition);

    my $host = Mojo::URL->new();
    $host->scheme('https');
    $host->host($api_host);
    $host->path($api_path);

    $client->base_url($host);

    $client->ua->on(
      start => sub ($ua, $tx) {

        $tx->req->headers->add("Accept" => "application/json");

        unless ($tx->req->headers->header('XSessionID')) {
          $tx->req->url->userinfo("$api_user:$api_key");
        }
      }
    );

    $client->ua->transactor->add_generator(
      'createData' => \&create_ticket_data);
}

sub create_ticket_data {
  my $t  = shift;
  my $tx = shift;

  $tx->req->headers->content_type('multipart/form-data');
  my $headers = $tx->req->headers;

  my $data = shift;

  my $xml     = Mojo::Content::Single->new();
  my $options = Mojo::Content::Single->new();

  $options->asset(
    Mojo::Asset::Memory->new->add_chunk(
      encode_json($data->{options})
    )
  );

  $xml->asset(Mojo::Asset::Memory->new->add_chunk($data->{xml}));

  $options->headers->content_disposition('form-data; name="options"');
  $xml->headers->content_disposition(
    'form-data; name="ticketData"; filename="ticketData.xml"');
  $xml->headers->content_type("text/xml");

  my @parts = ($options, $xml);

  $tx->req->content(
    Mojo::Content::MultiPart->new(
      headers => $headers,
      parts   => \@parts
    )
  );
}


method has_api_host {
    return $api_host ? 1 : 0;
}



method whoami($session_id = undef) {
    return $self->api_call('op_auth_whoami',
      { $session_id ? (XSessionID => $session_id) : () });
}


method logout($session_id = undef) {
    return $self->api_call('op_auth_logout',
      { $session_id ? (XSessionID => $session_id) : () });
}


method impersonate($username = undef, $uuid = undef, $session_id = undef) {
  return $self->api_call(
    'op_auth_impersonate',
    {
      $username   ? (userName   => $username)   : (),
      $uuid       ? (userUuid   => $uuid)       : (),
      $session_id ? (XSessionID => $session_id) : (),
    }
  );
}


method create_ticket($xml, $options, $session_id = undef) {

  return $self->api_call(
    'op_createTicket',
    {
      $session_id ? (XSessionID => $session_id) : (),
    },
    {
      createData => {
        options => $options,
        xml     => $xml,
      }
    }
  );
}


method start_document($url = undef, $uuid = undef, $session_id = undef) {
  return $self->api_call(
    'op_document_startDocument',
    {
      $session_id ? (XSessionID => $session_id) : (),
      $uuid ? (ticketUuid => $uuid) : (),
      $url ? (xmldataurl => $url) : (),
    }
  );
}


method build_document($close, $uuid, $session_id = undef) {
  return $self->api_call(
    'op_document_buildDocument',
    {
      close => $close ? $Types::Serialiser::true : $Types::Serialiser::false,
      documentUuid => $uuid,
      $session_id ? (XSessionID => $session_id) : (),
    }
  );
}


method api_call($operation, $query, $content = {}) {

    my $tx = try {
      $client->call($operation => $query, %$content);
    }
    catch {
      die("Died calling Xential API with operation '$operation': $_", $/);
    };

    if ($tx->error) {

      # Not found, no result
      return if $tx->res->code == 404;

      # Any other error
      croak(
        sprintf(
          "Error calling Xential API with operation '%s': '%s' (%s)",
          $operation, $tx->result->body, $tx->error->{message}
        ),
      );
    }

    return $tx->res->json;
}



1;

=pod

=encoding UTF-8

=head1 NAME

WebService::Xential - A Xential REST API module

=head1 VERSION

version 0.004

=head1 SYNOPSIS

    my $xential = WebService::Xential->new(
      api_user => 'foo',
      api_key => 'foo',
      api_host => '127.0.0.1',
    );

    my $who   = $xential->whoami();
    my $other = $xential->impersonate(..., $who->{XSessionId});
    my $session_id = $other{XSessionID};

    my $ticket = $xential->create_ticket($xml, \%options, $session_id);
    my $start = $xential->start_document(
        $ticket->{startDocumentUrl},
        $ticket->{ticketUuid},
        $session_id
    );

    # Status is either INVALID or VALID

    if ($start->{status} eq 'VALID') {
        my $build = $xential->build_document(
            1,
            $start->{documentUuid},
            $session_id
        );

        if ($build->{status} eq 'done') {
            # build succeeded
        }
        else {
            # build failed
        }
    }
    else {
        use URI;
        $uri = URI->new($start{resumeUrl});
        $uri->scheme('https');
        $uri->query_form($uri->query_form, afterOpenAction => 'close');
        $uri->host($xential->api_host);
        # redirect user to $uri
    }

=head1 DESCRIPTION

This module implements the REST API of Xential.

=head1 ATTRIBUTES

=head2 api_host

The API host of the Xential WebService

=head2 client

The L

=head1 METHODS

=head2 new()

    my $xential = WebService::Xential->new(
      api_user => 'foo',
      api_key => 'foo',
      api_host => '127.0.0.1',
    );

=head2 has_api_host()

Tells you if you have a custom API host defined

=head2 whoami($session_id)

Implements the whoami call from Xential

=head2 logout($session_id)

Implements the logout call from Xential

=head2 impersonate($username, $user_uuid, $session_id)

Implements the impersonate call from Xential

=head2 create_ticket($xml, $options, $session_id)

Implements the create_ticket call from Xential

=head2 start_document($username, $user_uuid, $session_id)

Implements the start_document call from Xential

=head2 build_document($username, $user_uuid, $session_id)

Implements the build_document call from Xential

=head2 api_call($operation, $query, $content)

A wrapper around the L function. Returns the JSON from
the endpoint.

=head1 AUTHOR

Wesley Schwengle

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2024 by Wesley Schwengle.

This is free software, licensed under:

  The (three-clause) BSD License

=cut

__DATA__