File Coverage

blib/lib/Lib/Pepper/Simple.pm

Criterion	Covered	Total	%
statement	64	300	21.3
branch	9	128	7.0
condition	1	95	1.0
subroutine	17	26	65.3
pod	6	6	100.0
total	97	555	17.4

package Lib::Pepper::Simple;
#---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::Instance;
use Lib::Pepper::OptionList;
use Lib::Pepper::Constants qw(:all);

# Package-level state for multi-terminal support
# These variables track the library initialization state across all instances
our $LIBRARY_INITIALIZED = 0;           # Boolean: Library initialized in this process?
our $INSTANCE_COUNT = 0;                # Integer: Number of active instances
our $INIT_LIBRARY_PATH = '';            # String: Library path used for initialization
our $INIT_CONFIG_XML = undef;           # String: Config XML used for initialization
our $INIT_LICENSE_XML = undef;          # String: License XML used for initialization
our %INSTANCE_ID_COUNTERS = ();         # Hash: terminal_type => next_available_id

# High-level wrapper for Lib::Pepper providing simple payment terminal operations

sub new($proto, %params) {
    my $class = ref($proto) || $proto;

    # Validate required parameters
    if(!defined $params{terminal_type}) {
        croak("new: terminal_type parameter is required");
    }
    if(!defined $params{terminal_address}) {
        croak("new: terminal_address parameter is required");
    }

    # Handle config: accept either config_file OR config_xml
    my $configXml;
    if(defined $params{config_xml}) {
        $configXml = $params{config_xml};
    } elsif(defined $params{config_file}) {
        # Load config from file
        if(!-f $params{config_file}) {
            croak("new: config_file '$params{config_file}' does not exist");
        }
        open(my $fh, '<', $params{config_file}) or croak("new: cannot open config_file '$params{config_file}': $ERRNO");
        $configXml = do { local $INPUT_RECORD_SEPARATOR = undef; <$fh> };
        close($fh);
    } else {
        croak("new: either config_xml or config_file parameter is required");
    }

    # Handle license: accept either license_file OR license_xml
    my $licenseXml;
    if(defined $params{license_xml}) {
        $licenseXml = $params{license_xml};
    } elsif(defined $params{license_file}) {
        # Load license from file
        if(!-f $params{license_file}) {
            croak("new: license_file '$params{license_file}' does not exist");
        }
        open(my $fh, '<', $params{license_file}) or croak("new: cannot open license_file '$params{license_file}': $ERRNO");
        $licenseXml = do { local $INPUT_RECORD_SEPARATOR = undef; <$fh> };
        close($fh);
    } else {
        croak("new: either license_xml or license_file parameter is required");
    }

    # Create object with default values
    my $self = bless {
        # Library state
        initialized      => 0,
        library_path     => $params{library_path} // '',
        config_xml       => $configXml,
        license_xml      => $licenseXml,

        # Instance state
        instance         => undef,
        terminal_type    => $params{terminal_type},
        terminal_address => $params{terminal_address},
        configured       => 0,

        # Configuration
        pos_number           => $params{pos_number} // '0001',
        merchant_password    => $params{merchant_password} // '000000',
        language             => $params{language} // PEP_LANGUAGE_ENGLISH,
        ticket_width         => $params{ticket_width} // 40,
        ticket_printing_mode => $params{ticket_printing_mode} // 0,  # Default: POS prints (disables terminal printer)
        tip_enabled          => $params{tip_enabled} // 0,         # Default: no tip dialog

        # Callback handling
        callback         => $params{callback},
        userdata         => $params{userdata} // {},

        # Logging
        reph             => $params{reph},  # Optional reporting handler with debuglog() method

        # State tracking
        connection_open  => 0,
        last_error       => undef,
        last_transaction => undef,

        # Multi-instance support: Track if this instance was counted
        _instance_counted => 0,  # Set to 1 only after successful initialization
    }, $class;

    # Set config_byte based on ticket_printing_mode if not explicitly provided
    # Mode 1 (EFT prints) = PEP_CONFIG_BYTE_NORMAL (normal operation)
    # Mode 0 (POS prints) = PEP_CONFIG_BYTE_DISABLE_PRINTER (disable terminal printer)
    # Other modes = PEP_CONFIG_BYTE_NORMAL (normal operation)
    if(exists $params{config_byte}) {
        # User explicitly provided config_byte, use it
        $self->{config_byte} = $params{config_byte};
    } else {
        # Auto-calculate based on ticket_printing_mode
        $self->{config_byte} = ($self->{ticket_printing_mode} == 0)
            ? PEP_CONFIG_BYTE_DISABLE_PRINTER
            : PEP_CONFIG_BYTE_NORMAL;
    }

    # Handle CARDTYPES_AUTODETECT placeholder if present
    if($self->{config_xml} =~ /CARDTYPES_AUTODETECT/) {
        my $cardtypesPath = Lib::Pepper->cardtypesFile();
        if(!defined $cardtypesPath) {
            croak("Could not find installed pepper_cardtypes.xml file");
        }
        $self->{config_xml} =~ s/CARDTYPES_AUTODETECT/$cardtypesPath/g;
    }

    # Attempt full initialization
    my $success = 0;
    my $needsInitialization = !$LIBRARY_INITIALIZED;  # Declared before eval for error handling

    eval {

        # ========================================
        # MULTI-INSTANCE SUPPORT: Library initialization
        # ========================================
        # Initialize Pepper library only if not already initialized
        # This allows multiple terminals to share the same library instance

        if($needsInitialization) {
            # First instance - initialize library
            Lib::Pepper->initialize(
                library_path => $self->{library_path},
                config_xml   => $self->{config_xml},
                license_xml  => $self->{license_xml},
            );

            # Store initialization parameters for validation of subsequent instances
            $INIT_LIBRARY_PATH = $self->{library_path};
            $INIT_CONFIG_XML = $self->{config_xml};
            $INIT_LICENSE_XML = $self->{license_xml};
            $LIBRARY_INITIALIZED = 1;

            $self->{initialized} = 1;
        } else {
            # Library already initialized - validate config compatibility
            if(!_validate_config($self->{library_path}, $self->{config_xml}, $self->{license_xml})) {
                croak("Configuration mismatch: Lib::Pepper library already initialized with different config. " .
                      "All Lib::Pepper::Simple instances in the same process must use identical " .
                      "library_path, config_xml, and license_xml parameters.");
            }
            $self->{initialized} = 1;  # Library is already initialized
        }

        # ========================================
        # MULTI-INSTANCE SUPPORT: Instance ID allocation
        # ========================================
        # Allocate instance_id automatically if not provided by user
        # Instance IDs are managed per terminal_type
        my $instanceId = $params{instance_id};
        if(!defined $instanceId) {
            $instanceId = _allocate_instance_id($self->{terminal_type});
        }
        # Store instance_id in object for status reporting
        $self->{instance_id} = $instanceId;

        # Create instance
        $self->{instance} = Lib::Pepper::Instance->new(
            terminal_type => $self->{terminal_type},
            instance_id   => $instanceId,
            reph          => $self->{reph},  # Pass reporting handler down
        );

        # Configure instance
        my $configResult = $self->{instance}->configure(
            callback => $self->{callback} // \&_defaultCallback,
            options  => {
                sHostName                => $self->{terminal_address},
                iLanguageValue           => $self->{language},
                sPosIdentificationString => $self->{pos_number},
                iTicketWidthValue        => $self->{ticket_width},
                iConfigByteValue         => $self->{config_byte},
                sMerchantPasswordString  => $self->{merchant_password},
                iTicketPrintingModeValue => $self->{ticket_printing_mode},
            },
            userdata => $self->{userdata},
        );
        $self->{configured} = 1;

        # Check and handle recovery flag automatically
        if(defined $configResult) {
            my $configData = $configResult->toHashref();
            my $recoveryFlag = $configData->{iRecoveryFlag} // 0;

            if($recoveryFlag) {
                # Perform recovery operation automatically
                my $recoveryOptions = Lib::Pepper::OptionList->new();

                my ($op1, $out1) = $self->{instance}->prepareOperation(PEP_OPERATION_RECOVERY, $recoveryOptions);
                my ($op2, $out2) = $self->{instance}->startOperation(PEP_OPERATION_RECOVERY, $recoveryOptions);
                my ($op3, $out3) = $self->{instance}->executeOperation(PEP_OPERATION_RECOVERY, $recoveryOptions);
                my ($op4, $out4) = $self->{instance}->finalizeOperation(PEP_OPERATION_RECOVERY, $recoveryOptions);

                my $recoveryStatus = $self->{instance}->operationStatus($op4, 1);
                if(!$recoveryStatus) {
                    croak("Recovery operation did not complete successfully");
                }
            }
        }

        # Open connection (required for ZVT terminals)
        my $openResult = $self->{instance}->openConnection(
            options => {
                sOperatorIdentificationString => $params{operator_id} // 'OPERATOR01',
            }
        );

        # Wait for OPEN to complete if pending
        if(!$openResult->{status}) {
            my $opHandle = $openResult->{operation_handle};
            my $waitStatus = $self->{instance}->operationStatus($opHandle, 1);
            if(!$waitStatus) {
                croak("OPEN operation did not complete successfully");
            }
        }
        $self->{connection_open} = 1;

        $success = 1;
    };

    if(!$success) {
        my $error = $EVAL_ERROR;

        # ========================================
        # MULTI-INSTANCE SUPPORT: Cleanup on failure
        # ========================================
        # Note: We do NOT finalize the library on failure.
        # The library stays initialized, allowing retry attempts.
        # Instance counter was NOT incremented yet, so nothing to decrement.
        # This is consistent with our never-finalize design.

        croak("Failed to initialize Lib::Pepper::Simple: $error");
    }

    # ========================================
    # MULTI-INSTANCE SUPPORT: Increment instance counter
    # ========================================
    # Only increment after successful initialization
    # This ensures the counter stays accurate even if initialization fails
    $INSTANCE_COUNT++;
    $self->{_instance_counted} = 1;  # Mark that this instance was counted

    return $self;
}

sub checkStatus($self) {
    my $status = {
        # Instance-level status
        library_initialized   => $self->{initialized},
        instance_configured   => $self->{configured},
        connection_open       => $self->{connection_open},
        terminal_type         => $self->{terminal_type},
        terminal_address      => $self->{terminal_address},
        instance_id           => $self->{instance_id},
        ready_for_transactions => 0,
        last_error            => $self->{last_error},

        # Process-level status (multi-terminal support)
        process_instance_count       => $INSTANCE_COUNT,
        process_library_initialized  => $LIBRARY_INITIALIZED,
    };

    # Ready if all critical components are initialized
    $status->{ready_for_transactions} = (
        $status->{library_initialized} &&
        $status->{instance_configured} &&
        $status->{connection_open}
    );

    return $status;
}

sub doPayment($self, $amount, %options) {
    # Validate state
    if(!$self->{connection_open}) {
        croak("doPayment: connection not open");
    }
    if(!$self->{configured}) {
        croak("doPayment: instance not configured");
    }

    # Validate amount
    if(!defined $amount || $amount !~ /^\d+$/ || $amount <= 0) {
        croak("doPayment: amount must be a positive integer (cents)");
    }

    # Build transaction parameters
    my $transactionType = $options{transaction_type} // PEP_TRANSACTION_TYPE_GOODS_PAYMENT;

    # Convert string transaction types to constants
    if(defined $transactionType && $transactionType !~ /^\d+$/) {
        if($transactionType eq 'goods') {
            $transactionType = PEP_TRANSACTION_TYPE_GOODS_PAYMENT;
        } else {
            croak("doPayment: invalid transaction_type '$transactionType' (use 'goods' or numeric constant)");
        }
    }

    my $currency = $options{currency};

    # Build additional options for the transaction
    my $txnOptions = $options{options} // {};

    # Tip support via Pepper API:
    # - Transaction type 13 (GoodsPaymentWithTip): NOT supported by GlobalPayments ZVT (returns -1402)
    # - iServiceByteValue bit 3 (tippable): Transaction completes but tip dialog depends on terminal config
    # - The tip prompt/dialog must be enabled at the TERMINAL level by your payment processor
    # - If you need tips, either:
    #   1. Contact GlobalPayments to enable tip prompting on your terminal
    #   2. Collect tip amount in your POS and pass it via doPayment(..., options => {iTipAmount => $tip})
    if($self->{tip_enabled}) {
        if(!exists $txnOptions->{iServiceByteValue}) {
            $txnOptions->{iServiceByteValue} = 8;  # Bit 3 = tippable
        } else {
            $txnOptions->{iServiceByteValue} |= 8;
        }
    }

    # Execute transaction
    my $result;
    my $success = 0;
    eval {
        $result = $self->{instance}->transaction(
            amount           => $amount,
            transaction_type => $transactionType,
            (defined $currency ? (currency => $currency) : ()),
            (keys %{$txnOptions} ? (options => $txnOptions) : ()),
        );
        $success = 1;
    };

    if(!$success) {
        $self->{last_error} = $EVAL_ERROR;
        return {
            success    => 0,
            authorized => 0,
            error      => $EVAL_ERROR,
        };
    }

    # Parse result output
    my $outputData = {};
    if(defined $result->{output}) {
        $outputData = $result->{output}->toHashref();
    }

    # Extract transaction result - CRITICAL: check iTransactionResultValue, not iFunctionResultValue!
    my $transactionResult = $outputData->{iTransactionResultValue} // -999;
    my $transactionText = $outputData->{sTransactionText} || '';

    # Build response
    my $response = {
        success            => $result->{status} ? 1 : 0,
        authorized         => ($transactionResult == 0) ? 1 : 0,
        amount_charged     => ($transactionResult == 0) ? $amount : 0,
        transaction_result => $transactionResult,
        transaction_text   => $transactionText,
        trace_number       => $outputData->{sTraceNumberString} || undef,
        authorization_code => $outputData->{sAuthorizationNumberString} || undef,
        reference_number   => $outputData->{sTransactionReferenceNumberString} || undef,
        terminal_id        => $outputData->{sTerminalIdentificationString} || undef,
        card_type          => $outputData->{sCardNameString} || undef,
        card_number        => $outputData->{sCardNumberString} || undef,
        transaction_date   => $outputData->{sTransactionDate} || undef,
        transaction_time   => $outputData->{sTransactionTime} || undef,
        raw_output         => $outputData,
    };

    # Store last transaction details
    $self->{last_transaction} = $response;
    $self->{last_error} = undef;

    return $response;
}

sub cancelPayment($self, $traceNumber, $amount, %options) {
    # Validate state
    if(!$self->{connection_open}) {
        croak("cancelPayment: connection not open");
    }
    if(!$self->{configured}) {
        croak("cancelPayment: instance not configured");
    }

    # Validate parameters
    if(!defined $traceNumber) {
        croak("cancelPayment: trace_number parameter is required");
    }
    if(!defined $amount || $amount !~ /^\d+$/ || $amount <= 0) {
        croak("cancelPayment: amount must be a positive integer (cents)");
    }
    if(!exists $options{reference_number} || !defined $options{reference_number}) {
        croak("cancelPayment: reference_number parameter is required for card-not-present refunds");
    }

    my $response = {
        success          => 0,
        trace_number     => undef,
        amount_refunded  => 0,
        transaction_text => '',
        raw_output       => {},
    };

    # Perform VOID (Transaction Type 12 - VoidGoodsPayment)
    # Using sTransactionReferenceNumberString for referenced void
    #
    # IMPORTANT: Despite being called "VOID", this works AFTER settlement when using
    # the reference number. This is the correct ZVT method for card-not-present refunds.
    # Transaction Type 41 (Credit) would require card swipe even with reference number.
    #
    # This discovery is not documented in Pepper docs but confirmed working on GP PAY
    # terminals with Generic ZVT protocol.
    my $refundResult;
    my $refundSuccess = 0;

    eval {
        # Build options for referenced void (no card required)
        my $refundOptions = {
            sTransactionReferenceNumberString => $options{reference_number},
        };

        if($ENV{DEBUG_PEPPER}) {
            $self->_log("=== VOID/REFUND Parameters ===");
            $self->_log("Transaction Type: VoidGoodsPayment (12)");
            $self->_log("Amount: $amount");
            for my $key (sort keys %{$refundOptions}) {
                $self->_log("$key: $refundOptions->{$key}");
            }
        }

        $refundResult = $self->{instance}->transaction(
            amount           => $amount,
            transaction_type => PEP_TRANSACTION_TYPE_VOID_GOODS_PAYMENT,
            options          => $refundOptions,
        );
        $refundSuccess = 1;
    };

    if(!$refundSuccess) {
        $self->{last_error} = "REFUND failed: $EVAL_ERROR";
        return $response;
    }

    if($ENV{DEBUG_PEPPER}) {
        $self->_log("=== REFUND Result Check ===");
        $self->_log("refundSuccess = $refundSuccess");
        $self->_log("refundResult defined = " . (defined $refundResult ? 'YES' : 'NO'));
        if(defined $refundResult) {
            $self->_log("refundResult->{output} defined = " . (defined $refundResult->{output} ? 'YES' : 'NO'));
        }
    }

    if(defined $refundResult->{output}) {
        my $refundData = $refundResult->{output}->toHashref();
        my $refundTransResult = $refundData->{iTransactionResultValue} // -999;
        my $refundTransText = $refundData->{sTransactionText} || '';

        if($ENV{DEBUG_PEPPER}) {
            $self->_log("iTransactionResultValue: $refundTransResult");
            $self->_log("sTransactionText: '$refundTransText'");
        }

        $response->{transaction_text} = $refundTransText;
        $response->{raw_output} = $refundData;

        if($refundTransResult == 0) {
            # REFUND succeeded!
            $response->{success} = 1;
            $response->{trace_number} = $refundData->{sTraceNumberString} || undef;
            $response->{amount_refunded} = $amount;

            $self->{last_error} = undef;
            return $response;
        } else {
            # REFUND failed
            $self->{last_error} = "REFUND failed: $refundTransText";
            return $response;
        }
    }

    $self->{last_error} = "REFUND failed: no output data";
    return $response;
}

sub endOfDay($self, %options) {
    # Validate state
    if(!$self->{connection_open}) {
        croak("endOfDay: connection not open");
    }
    if(!$self->{configured}) {
        croak("endOfDay: instance not configured");
    }

    # Execute settlement operation
    my $result;
    my $success = 0;
    eval {
        $result = $self->{instance}->settlement(
            options => $options{options} // {},
        );
        $success = 1;
    };

    if(!$success) {
        $self->{last_error} = $EVAL_ERROR;
        return {
            success => 0,
            error   => $EVAL_ERROR,
        };
    }

    # Parse settlement output
    my $outputData = {};
    if(defined $result->{output}) {
        $outputData = $result->{output}->toHashref();
    }

    # Check settlement result (use iFunctionResultValue for settlement)
    my $functionResult = $outputData->{iFunctionResultValue} // -999;
    my $functionText = $outputData->{sFunctionText} || '';

    # Build response
    my $response = {
        success           => ($functionResult == 0) ? 1 : 0,
        function_result   => $functionResult,
        function_text     => $functionText,
        transaction_count => $outputData->{iNumberOfTransactions} || 0,
        total_amount      => $outputData->{iTotalAmount} || 0,
        settlement_date   => $outputData->{sSettlementDate} || undef,
        settlement_time   => $outputData->{sSettlementTime} || undef,
        raw_output        => $outputData,
    };

    $self->{last_error} = ($functionResult == 0) ? undef : $functionText;

    return $response;
}

# Allocate a unique instance_id for the given terminal_type
# Instance IDs are managed per terminal type (e.g., Generic ZVT terminals get IDs 1, 2, 3, ...)
sub _allocate_instance_id($terminal_type) {
    # Initialize counter for this terminal type if not exists
    $INSTANCE_ID_COUNTERS{$terminal_type} //= 1;

    # Get current ID and increment for next time
    my $id = $INSTANCE_ID_COUNTERS{$terminal_type};
    $INSTANCE_ID_COUNTERS{$terminal_type}++;

    return $id;
}

# Validate that library initialization parameters match the first instance
# Returns 1 if valid, 0 if mismatch detected
sub _validate_config($library_path, $config_xml, $license_xml) {
    # If library not initialized yet, any config is valid (this is first instance)
    return 1 if !$LIBRARY_INITIALIZED;

    # Validate library_path matches
    if($library_path ne $INIT_LIBRARY_PATH) {
        return 0;
    }

    # Validate config_xml matches (strict - must be identical)
    if($config_xml ne $INIT_CONFIG_XML) {
        return 0;
    }

    # Validate license_xml matches
    if($license_xml ne $INIT_LICENSE_XML) {
        return 0;
    }

    return 1;
}

# Class method to check process-wide library status
# Returns hashref with library state information
sub library_status($class) {
    return {
        initialized     => $LIBRARY_INITIALIZED,
        instance_count  => $INSTANCE_COUNT,
        library_path    => $INIT_LIBRARY_PATH,
        instance_ids    => { %INSTANCE_ID_COUNTERS },
    };
}

sub DESTROY($self) {
    # Cleanup instance resources
    if($self->{instance}) {
        eval {
            # Connection cleanup handled by Instance destructor
            undef $self->{instance};
        };
    }

    # ========================================
    # MULTI-INSTANCE SUPPORT: Reference counting
    # ========================================
    # CRITICAL: Only decrement if this instance was actually counted!
    # If constructor failed before incrementing, don't decrement
    return unless $self->{_instance_counted};

    # Decrement the instance counter
    $INSTANCE_COUNT--;

    # ========================================
    # DESIGN DECISION: Never finalize the library
    # ========================================
    # The Pepper C library has a critical limitation: once pepFinalize() is called,
    # pepInitialize() cannot be called again in the same process (returns error -103).
    #
    # SOLUTION: We never call pepFinalize(), keeping the library loaded in memory.
    # This allows creating new instances even after all previous instances are destroyed.
    #
    # Trade-offs:
    #   PRO: Can create instances → destroy all → create new instances ✓
    #   PRO: No -103 errors, can run unlimited test iterations ✓
    #   PRO: Simpler lifecycle management ✓
    #   CON: Library stays in memory until process exit (~few MB)
    #   CON: Cannot reset library state without restarting process
    #
    # Note: Instance-level resources (connections, handles) are still properly cleaned up.
    #       Only the library initialization state persists.

    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;
}

# Default callback if user doesn't provide one
sub _defaultCallback {
    # Silent default callback - user can provide their own for logging/debugging
    return;
}

1;
__END__