refactor: split buspro ApiClient into domain clients

src/BusProNet/Client/VoucherClient.php

@@ -0,0 +1,121 @@
+<?php
+
+namespace App\BusProNet\Client;
+
+use App\BusProNet\Constants;
+use App\BusProNet\DataProcessor\VoucherSalePayloadBuilder;
+use App\BusProNet\Exception\ApiClientException;
+use App\BusProNet\MessageType;
+use App\BusProNet\Model\Notification;
+use App\BusProNet\Model\PromoVoucher;
+use App\BusProNet\Model\PurchaseVoucher;
+use App\BusProNet\Model\VoucherPaymentMethod;
+use App\BusProNet\Model\VoucherPreview;
+use App\BusProNet\Model\VoucherSaleResponse;
+use App\BusProNet\Model\VoucherTemplates;
+use App\BusProNet\Transport\XmlChannel;
+use App\Form\Model\VoucherPurchaseDto;
+
+/**
+ * Redeeming vouchers in a booking, and selling purchase vouchers (Kaufgutscheine).
+ */
+class VoucherClient
+{
+    public function __construct(
+        private readonly XmlChannel $channel,
+        private readonly VoucherSalePayloadBuilder $voucherSalePayloadBuilder,
+    ) {
+    }
+
+    /**
+     * Looks up a purchase voucher (Gutschein) by its redemption code. Purchase vouchers, regular
+     * or goodwill (Kulanz), carry a balance that each redemption reduces.
+     *
+     * @throws ApiClientException
+     */
+    public function validatePurchaseVoucher(string $redemptionCode): Notification|PurchaseVoucher
+    {
+        return $this->channel->request(MessageType::PurchaseVoucher, ['einloesecode' => $redemptionCode]);
+    }
+
+    /**
+     * Validates a promo voucher (Aktionsgutschein) for a travel and participant price. Promo
+     * vouchers are absolute discounts, per person ("P") or per booking ("B") as pro_buchung_person
+     * says.
+     *
+     * @throws ApiClientException
+     */
+    public function validatePromoVoucher(string $promoCode, int $travelId, float $participantPrice): Notification|PromoVoucher
+    {
+        return $this->channel->request(MessageType::PromoVoucher, [
+            'aktionsgutschein' => $promoCode,
+            'idreise' => $travelId,
+            'preis' => number_format($participantPrice, 2, ',', ''),
+        ]);
+    }
+
+    /**
+     * Fetches the voucher designs on sale and the amount bounds.
+     *
+     * @throws ApiClientException
+     */
+    public function getVoucherTemplates(): Notification|VoucherTemplates
+    {
+        return $this->channel->request(MessageType::VoucherTemplates);
+    }
+
+    /**
+     * Fetches the payment methods offered for voucher purchases.
+     *
+     * @return list<VoucherPaymentMethod>|Notification
+     *
+     * @throws ApiClientException
+     */
+    public function getVoucherPaymentMethods(): array|Notification
+    {
+        return $this->channel->request(MessageType::VoucherPaymentMethods);
+    }
+
+    /**
+     * Renders the PDF preview of a voucher design with the entered data.
+     *
+     * @throws ApiClientException
+     */
+    public function getVoucherPreview(VoucherPurchaseDto $voucherPurchaseDto): Notification|VoucherPreview
+    {
+        return $this->channel->request(MessageType::VoucherPreview, $this->voucherSalePayloadBuilder->buildPreviewPayload($voucherPurchaseDto));
+    }
+
+    /**
+     * Dry run of a voucher purchase: full validation, nothing is issued.
+     *
+     * Every HINWEIS is a rejection on this path, including 650 (missing address data), so the
+     * result must not be judged by Notification::isError().
+     *
+     * @throws ApiClientException
+     */
+    public function createVoucherSaleInquiry(VoucherPurchaseDto $voucherPurchaseDto): Notification|VoucherSaleResponse
+    {
+        return $this->sendVoucherSale($voucherPurchaseDto, Constants::BOOKING_TYPE_INQUIRY);
+    }
+
+    /**
+     * Buys the voucher. BusPro mails it to the buyer once the payment has arrived.
+     *
+     * Every HINWEIS is a rejection on this path, including 650.
+     *
+     * @throws ApiClientException
+     */
+    public function createVoucherSale(VoucherPurchaseDto $voucherPurchaseDto): Notification|VoucherSaleResponse
+    {
+        return $this->sendVoucherSale($voucherPurchaseDto, Constants::BOOKING_TYPE_BOOKING);
+    }
+
+    /**
+     * @throws ApiClientException
+     */
+    private function sendVoucherSale(VoucherPurchaseDto $voucherPurchaseDto, string $saleType): Notification|VoucherSaleResponse
+    {
+        return $this->channel->request(MessageType::VoucherSale, $this->voucherSalePayloadBuilder->buildSalePayload($voucherPurchaseDto, $saleType));
+    }
+}