File Coverage

blib/lib/Lib/Pepper/Instance.pm

Criterion	Covered	Total	%
statement	44	296	14.8
branch	0	112	0.0
condition	0	36	0.0
subroutine	15	32	46.8
pod	15	15	100.0
total	74	491	15.0

package Lib::Pepper::Instance;
#---AUTOPRAGMASTART---
use v5.42;
use strict;
use diagnostics;
use mro 'c3';
use English;
use Carp qw[carp croak confess cluck longmess shortmess];
our $VERSION = 0.5;
use autodie qw( close );
use Array::Contains;
use utf8;
use Data::Dumper;
use Data::Printer;
#---AUTOPRAGMAEND---


use Lib::Pepper;
use Lib::Pepper::Exception;
use Lib::Pepper::OptionList;
use Lib::Pepper::Constants qw(:all);

sub new($class, %params) {
    my $terminalType = $params{terminal_type};
    my $instanceId = $params{instance_id} || 1;

    if(!defined $terminalType) {
        croak('new: terminal_type parameter is required');
    }

    my $self = {
        handle         => undef,
        terminal_type  => $terminalType,
        instance_id    => $instanceId,
        configured     => 0,
        callback       => undef,
        userdata       => undef,
        reph           => $params{reph},  # Optional reporting handler
    };

    bless $self, $class;

    # Create the instance
    my ($result, $handle) = Lib::Pepper::pepCreateInstance($terminalType, $instanceId);
    Lib::Pepper::Exception->checkResult($result, 'pepCreateInstance');

    $self->{handle} = $handle;

    return $self;
}

sub getHandle($self) {
    return $self->{handle};
}

sub isConfigured($self) {
    return $self->{configured};
}

sub configure($self, %params) {
    if(!defined $self->{handle}) {
        croak('configure: instance not initialized');
    }

    my $callback = $params{callback};
    my $options = $params{options} || {};
    my $userdata = $params{userdata};

    if(!defined $callback || ref($callback) ne 'CODE') {
        croak('configure: callback parameter must be a code reference');
    }

    # Create option list manually to handle callback values properly
    my $inputOptions = Lib::Pepper::OptionList->new();

    # Add callback configuration (mandatory for pepConfigure)
    # Default to receiving both output and input callbacks with all options
    my $callbackEvent = $options->{iCallbackEventValue} //
        (PEP_CALLBACK_EVENT_OUTPUT | PEP_CALLBACK_EVENT_INPUT);
    my $callbackOption = $options->{iCallbackOptionValue} //
        (PEP_CALLBACK_OPTION_INTERMEDIATE_STATUS | PEP_CALLBACK_OPTION_OPERATION_FINISHED |
         PEP_CALLBACK_OPTION_INTERMEDIATE_TICKET |
         PEP_CALLBACK_OPTION_SELECTION_LIST | PEP_CALLBACK_OPTION_NUMERICAL_INPUT |
         PEP_CALLBACK_OPTION_ALPHANUMERICAL_INPUT | PEP_CALLBACK_OPTION_COMPLEX_INPUT);

    $inputOptions->addInt('iCallbackEventValue', $callbackEvent);
    $inputOptions->addInt('iCallbackOptionValue', $callbackOption);

    # Add other options
    for my $key (keys %{$options}) {
        next if $key eq 'iCallbackEventValue';
        next if $key eq 'iCallbackOptionValue';

        my $value = $options->{$key};
        if(!defined $value) {
            next;
        } elsif(ref($value) eq 'HASH') {
            my $childList = Lib::Pepper::OptionList->fromHashref($value);
            $inputOptions->addChild($key, $childList);
        } elsif(ref($value) eq '') {
            # Use key prefix to determine type: i=int, s=string, h=handle/child
            if($key =~ /^i/) {
                $inputOptions->addInt($key, $value);
            } else {
                $inputOptions->addString($key, $value);
            }
        }
    }

    # Store callback and userdata
    $self->{callback} = $callback;
    $self->{userdata} = $userdata;

    # Configure with callback
    my ($result, $outputOptions) = Lib::Pepper::pepConfigureWithCallback(
        $self->{handle},
        $inputOptions->getHandle(),
        $callback,
        $userdata
    );

    Lib::Pepper::Exception->checkResult($result, 'pepConfigure');

    $self->{configured} = 1;

    # Return output options as OptionList object
    if(defined $outputOptions) {
        return Lib::Pepper::OptionList->new($outputOptions);
    }

    return;
}

sub prepareOperation($self, $operation, $inputOptions = undef) {
    if(!defined $self->{handle}) {
        croak('prepareOperation: instance not initialized');
    }

    if(!$self->{configured}) {
        croak('prepareOperation: instance not configured');
    }

    my $inputHandle = defined $inputOptions ? $inputOptions->getHandle() : PEP_INVALID_HANDLE;

    my ($result, $operationHandle, $outputHandle) = Lib::Pepper::pepPrepareOperation(
        $self->{handle},
        $operation,
        $inputHandle
    );

    # Provide helpful context for state transition errors
    if($result == -1301) {
        my $termType = $self->{terminal_type} || 'unknown';
        my $opName = $operation == 4 ? 'TRANSACTION' :
                     $operation == 5 ? 'SETTLEMENT' :
                     $operation == 1 ? 'OPEN' :
                     $operation == 2 ? 'CLOSE' : $operation;

        my $extraMsg = '';
        if($termType == 999 || $termType eq PEP_TERMINAL_TYPE_MOCK) {
            $extraMsg = "\n\nNOTE: Mock terminals (TT999) do NOT support transaction operations.\n" .
                       "This is expected behavior. For transaction testing, use:\n" .
                       "  - PEP_TERMINAL_TYPE_GENERIC_ZVT (118) - Generic ZVT terminals\n" .
                       "  - PEP_TERMINAL_TYPE_HOBEX_ZVT (120) - Hobex ZVT terminals\n" .
                       "See examples/README.md and IMPLEMENTATION_STATUS.md for details.";
        }

        croak("pepPrepareOperation: Invalid state transition (code: -1301)\n" .
              "Operation: $opName\n" .
              "Terminal Type: $termType\n" .
              "The instance is not in the correct state for this operation.$extraMsg");
    }

    Lib::Pepper::Exception->checkResult($result, 'pepPrepareOperation');

    return (
        $operationHandle,
        defined $outputHandle ? Lib::Pepper::OptionList->new($outputHandle) : undef
    );
}

sub startOperation($self, $operation, $inputOptions = undef) {
    if(!defined $self->{handle}) {
        croak('startOperation: instance not initialized');
    }

    if(!$self->{configured}) {
        croak('startOperation: instance not configured');
    }

    my $inputHandle = defined $inputOptions ? $inputOptions->getHandle() : PEP_INVALID_HANDLE;

    my ($result, $operationHandle, $outputHandle) = Lib::Pepper::pepStartOperation(
        $self->{handle},
        $operation,
        $inputHandle
    );

    Lib::Pepper::Exception->checkResult($result, 'pepStartOperation');

    return (
        $operationHandle,
        defined $outputHandle ? Lib::Pepper::OptionList->new($outputHandle) : undef
    );
}

sub executeOperation($self, $operation, $inputOptions = undef) {
    if(!defined $self->{handle}) {
        croak('executeOperation: instance not initialized');
    }

    if(!$self->{configured}) {
        croak('executeOperation: instance not configured');
    }

    my $inputHandle = defined $inputOptions ? $inputOptions->getHandle() : PEP_INVALID_HANDLE;

    my ($result, $operationHandle, $outputHandle) = Lib::Pepper::pepExecuteOperation(
        $self->{handle},
        $operation,
        $inputHandle
    );

    Lib::Pepper::Exception->checkResult($result, 'pepExecuteOperation');

    return (
        $operationHandle,
        defined $outputHandle ? Lib::Pepper::OptionList->new($outputHandle) : undef
    );
}

sub finalizeOperation($self, $operation, $inputOptions = undef) {
    if(!defined $self->{handle}) {
        croak('finalizeOperation: instance not initialized');
    }

    if(!$self->{configured}) {
        croak('finalizeOperation: instance not configured');
    }

    my $inputHandle = defined $inputOptions ? $inputOptions->getHandle() : PEP_INVALID_HANDLE;

    my ($result, $operationHandle, $outputHandle) = Lib::Pepper::pepFinalizeOperation(
        $self->{handle},
        $operation,
        $inputHandle
    );

    Lib::Pepper::Exception->checkResult($result, 'pepFinalizeOperation');

    return (
        $operationHandle,
        defined $outputHandle ? Lib::Pepper::OptionList->new($outputHandle) : undef
    );
}

sub operationStatus($self, $operationHandle, $waitForCompletion = 0) {
    if(!defined $self->{handle}) {
        croak('operationStatus: instance not initialized');
    }

    my ($result, $status) = Lib::Pepper::pepOperationStatus(
        $self->{handle},
        $operationHandle,
        $waitForCompletion
    );

    Lib::Pepper::Exception->checkResult($result, 'pepOperationStatus');

    return $status;
}

sub openConnection($self, %params) {
    if(!defined $self->{handle}) {
        croak('openConnection: instance not initialized');
    }

    if(!$self->{configured}) {
        croak('openConnection: instance not configured');
    }

    my $options = $params{options} || {};
    my $inputOptions = Lib::Pepper::OptionList->fromHashref($options);

    # Execute the OPEN operation using the 4-step workflow
    # All 4 steps should be called in sequence, then wait for completion at the end
    my ($opHandle1, $output1) = $self->prepareOperation(PEP_OPERATION_OPEN, $inputOptions);
    my ($opHandle2, $output2) = $self->startOperation(PEP_OPERATION_OPEN, $inputOptions);
    my ($opHandle3, $output3) = $self->executeOperation(PEP_OPERATION_OPEN, $inputOptions);
    my ($opHandle4, $output4) = $self->finalizeOperation(PEP_OPERATION_OPEN, $inputOptions);

    # Wait for the final step to complete
    my $status4 = $self->operationStatus($opHandle4, 1);

    return {
        operation_handle => $opHandle4,
        status          => $status4,
        output          => $output4,
    };
}

sub closeConnection($self, %params) {
    if(!defined $self->{handle}) {
        croak('closeConnection: instance not initialized');
    }

    if(!$self->{configured}) {
        croak('closeConnection: instance not configured');
    }

    my $options = $params{options} || {};
    my $inputOptions = Lib::Pepper::OptionList->fromHashref($options);

    # Execute the CLOSE operation using the 4-step workflow
    # All 4 steps should be called in sequence, then wait for completion at the end
    my ($opHandle1, $output1) = $self->prepareOperation(PEP_OPERATION_CLOSE, $inputOptions);
    my ($opHandle2, $output2) = $self->startOperation(PEP_OPERATION_CLOSE, $inputOptions);
    my ($opHandle3, $output3) = $self->executeOperation(PEP_OPERATION_CLOSE, $inputOptions);
    my ($opHandle4, $output4) = $self->finalizeOperation(PEP_OPERATION_CLOSE, $inputOptions);

    # Wait for the final step to complete
    my $status4 = $self->operationStatus($opHandle4, 1);

    return {
        operation_handle => $opHandle4,
        status          => $status4,
        output          => $output4,
    };
}

sub transaction($self, %params) {
    if(!defined $self->{handle}) {
        croak('transaction: instance not initialized');
    }

    if(!$self->{configured}) {
        croak('transaction: instance not configured');
    }

    my $transactionType = $params{transaction_type} || PEP_TRANSACTION_TYPE_GOODS_PAYMENT;
    my $amount = $params{amount};
    my $currency = $params{currency};
    my $additionalOptions = $params{options} || {};

    if(!defined $amount) {
        croak('transaction: amount parameter is required');
    }

    # Build input options for transaction
    # Real ZVT terminals require transaction parameters in operation options
    my $inputOptions = Lib::Pepper::OptionList->new();

    # Add mandatory transaction parameters
    $inputOptions->addInt('iTransactionTypeValue', $transactionType);
    $inputOptions->addInt('iAmount', $amount);

    # Add currency if specified (some terminals require it, others handle it via config)
    if(defined $currency) {
        $inputOptions->addInt('iCurrency', $currency);
    }

    # Add any additional user-specified options
    for my $key (keys %{$additionalOptions}) {
        my $value = $additionalOptions->{$key};
        next unless defined $value;

        if($key =~ /^i/) {
            $inputOptions->addInt($key, $value);
        } elsif($key =~ /^h/) {
            if(ref($value) && $value->isa('Lib::Pepper::OptionList')) {
                $inputOptions->addChild($key, $value);
            }
        } else {
            $inputOptions->addString($key, $value);
        }
    }

    # Execute the full 4-step workflow
    # All 4 steps should be called in sequence, then wait for completion at the end
    my ($opHandle1, $output1) = $self->prepareOperation(PEP_OPERATION_TRANSACTION, $inputOptions);
    my ($opHandle2, $output2) = $self->startOperation(PEP_OPERATION_TRANSACTION, $inputOptions);
    my ($opHandle3, $output3) = $self->executeOperation(PEP_OPERATION_TRANSACTION, $inputOptions);
    my ($opHandle4, $output4) = $self->finalizeOperation(PEP_OPERATION_TRANSACTION, $inputOptions);

    # Wait for the final step to complete
    my $status4 = $self->operationStatus($opHandle4, 1);

    # CRITICAL: Return value does NOT indicate payment success!
    # Check $output4->getInt('iTransactionResultValue') == 0 for payment authorization
    return {
        operation_handle => $opHandle4,
        status          => $status4,  # API completion status, NOT payment status
        output          => $output4,  # Contains iTransactionResultValue (0=authorized, -1=declined/aborted)
    };
}

sub settlement($self, %params) {
    if(!defined $self->{handle}) {
        croak('settlement: instance not initialized');
    }

    if(!$self->{configured}) {
        croak('settlement: instance not configured');
    }

    my $options = $params{options} || {};

    my $inputOptions = Lib::Pepper::OptionList->fromHashref($options);

    # Execute the full 4-step workflow
    # All 4 steps should be called in sequence, then wait for completion at the end
    my ($opHandle1, $output1) = $self->prepareOperation(PEP_OPERATION_SETTLEMENT, $inputOptions);
    my ($opHandle2, $output2) = $self->startOperation(PEP_OPERATION_SETTLEMENT, $inputOptions);
    my ($opHandle3, $output3) = $self->executeOperation(PEP_OPERATION_SETTLEMENT, $inputOptions);
    my ($opHandle4, $output4) = $self->finalizeOperation(PEP_OPERATION_SETTLEMENT, $inputOptions);

    # Wait for the final step to complete
    my $status4 = $self->operationStatus($opHandle4, 1);

    return {
        operation_handle => $opHandle4,
        status          => $status4,
        output          => $output4,
    };
}

sub utility($self, %params) {
    if(!defined $self->{handle}) {
        croak('utility: instance not initialized');
    }

    if(!$self->{configured}) {
        croak('utility: instance not configured');
    }

    my $options = $params{options} || {};
    my $inputOptions = Lib::Pepper::OptionList->fromHashref($options);

    my ($result, $outputHandle) = Lib::Pepper::pepUtility(
        $self->{handle},
        $inputOptions->getHandle()
    );

    Lib::Pepper::Exception->checkResult($result, 'pepUtility');

    return defined $outputHandle ? Lib::Pepper::OptionList->new($outputHandle) : undef;
}

sub auxiliary($self, %params) {
    if(!defined $self->{handle}) {
        croak('auxiliary: instance not initialized');
    }

    if(!$self->{configured}) {
        croak('auxiliary: instance not configured');
    }

    my $options = $params{options} || {};
    my $inputOptions = Lib::Pepper::OptionList->fromHashref($options);

    my ($result, $operationHandle, $outputHandle) = Lib::Pepper::pepAuxiliary(
        $self->{handle},
        $inputOptions->getHandle()
    );

    Lib::Pepper::Exception->checkResult($result, 'pepAuxiliary');

    return (
        $operationHandle,
        defined $outputHandle ? Lib::Pepper::OptionList->new($outputHandle) : undef
    );
}

sub DESTROY($self) {
    if(defined $self->{handle}) {
        my $result = Lib::Pepper::pepFreeInstance($self->{handle});
        # Don't croak in DESTROY - just warn on failure
        if($result < 0) {
            carp("Warning: pepFreeInstance failed with code: $result");
        }
        $self->{handle} = undef;
    }
    return;
}

# Internal logging helper - uses reph if available, falls back to STDERR
sub _log($self, @parts) {
    if($self->{reph} && $self->{reph}->can('debuglog')) {
        $self->{reph}->debuglog(@parts);
    } else {
        # Fallback to STDERR if no reph provided
        print STDERR join('', @parts), "\n";
    }
    return;
}

1;

__END__