dolibarr.bankimport/vendor/nemiah/php-fints/lib/Fhp/Action/GetStatementPDF.php

<?php

namespace Fhp\Action;

use Fhp\Model\SEPAAccount;
use Fhp\PaginateableAction;
use Fhp\Protocol\BPD;
use Fhp\Protocol\Message;
use Fhp\Protocol\UnexpectedResponseException;
use Fhp\Protocol\UPD;
use Fhp\Segment\Common\Kti;
use Fhp\Segment\EKP\HIEKP;
use Fhp\Segment\EKP\HIEKPSv2;
use Fhp\Segment\EKP\HKEKPv2;
use Fhp\Segment\HIRMS\Rueckmeldungscode;
use Fhp\UnsupportedException;

/**
 * Retrieves PDF bank statements (Elektronischer Kontoauszug) via HKEKP.
 */
class GetStatementPDF extends PaginateableAction
{
    /** @var SEPAAccount */
    private $account;

    /** @var int|null Optional: specific statement number */
    private $statementNumber;

    /** @var int|null Optional: statement year */
    private $statementYear;

    /** @var bool Whether PDF is base64 encoded (from BPD) */
    private $isBase64 = false;

    // Response data
    /** @var string Raw PDF data (may be from multiple pages) */
    private $pdfData = '';

    /** @var array Statement metadata from response */
    private $statementInfo = [];

    /**
     * @param SEPAAccount $account The account to get statements for
     * @param int|null $statementNumber Optional: Request specific statement by number
     * @param int|null $statementYear Optional: Year of the statement (required if number given)
     * @return GetStatementPDF
     */
    public static function create(
        SEPAAccount $account,
        ?int $statementNumber = null,
        ?int $statementYear = null
    ): GetStatementPDF {
        $result = new GetStatementPDF();
        $result->account = $account;
        $result->statementNumber = $statementNumber;
        $result->statementYear = $statementYear;
        return $result;
    }

    public function __serialize(): array
    {
        return [
            parent::__serialize(),
            $this->account,
            $this->statementNumber,
            $this->statementYear,
            $this->isBase64,
        ];
    }

    public function __unserialize(array $serialized): void
    {
        list(
            $parentSerialized,
            $this->account,
            $this->statementNumber,
            $this->statementYear,
            $this->isBase64
        ) = $serialized;

        is_array($parentSerialized)
            ? parent::__unserialize($parentSerialized)
            : parent::unserialize($parentSerialized);
    }

    /**
     * @return string The raw PDF data
     */
    public function getPdfData(): string
    {
        $this->ensureDone();

        // Decode base64 if needed
        if ($this->isBase64 && !empty($this->pdfData)) {
            $decoded = base64_decode($this->pdfData, true);
            if ($decoded !== false) {
                return $decoded;
            }
        }

        return $this->pdfData;
    }

    /**
     * @return array Statement metadata (number, year, iban, date, filename)
     */
    public function getStatementInfo(): array
    {
        $this->ensureDone();
        return $this->statementInfo;
    }

    /**
     * @return bool Whether receipt confirmation is needed
     */
    public function needsReceipt(): bool
    {
        $this->ensureDone();
        return !empty($this->statementInfo['receiptCode']);
    }

    /** {@inheritdoc} */
    protected function createRequest(BPD $bpd, ?UPD $upd)
    {
        /** @var HIEKPSv2|null $hiekps */
        $hiekps = $bpd->getLatestSupportedParameters('HIEKPS');

        if ($hiekps === null) {
            throw new UnsupportedException('The bank does not support PDF statements (HKEKP).');
        }

        $param = $hiekps->getParameter();
        $this->isBase64 = $param->isBase64Encoded();

        // Check if historical statements are allowed
        if ($this->statementNumber !== null && !$param->isHistoricalStatementsAllowed()) {
            throw new UnsupportedException('The bank does not allow requesting historical statements by number.');
        }

        return HKEKPv2::create(
            Kti::fromAccount($this->account),
            $this->statementNumber,
            $this->statementYear
        );
    }

    /** {@inheritdoc} */
    public function processResponse(Message $response)
    {
        parent::processResponse($response);

        // Check if no statements available
        if ($response->findRueckmeldung(Rueckmeldungscode::NICHT_VERFUEGBAR) !== null) {
            return;
        }

        /** @var HIEKP[] $responseSegments */
        $responseSegments = $response->findSegments(HIEKP::class);

        if (empty($responseSegments)) {
            // No segments but also no error = empty response
            return;
        }

        foreach ($responseSegments as $hiekp) {
            // Append PDF data (for pagination)
            $this->pdfData .= $hiekp->getPdfData();

            // Store metadata from first segment
            if (empty($this->statementInfo)) {
                $this->statementInfo = [
                    'statementNumber' => $hiekp->getStatementNumber(),
                    'statementYear' => $hiekp->getStatementYear(),
                    'iban' => $hiekp->getIban(),
                    'creationDate' => $hiekp->getCreationDate(),
                    'filename' => $hiekp->getFilename(),
                    'receiptCode' => $hiekp->needsReceipt() ? $hiekp->getReceiptCode() : null,
                ];
            }
        }
    }
}