Merge pull request #162 from alma/release/v2.5.0

Release v2.5.0

.pre-commit-config.yaml

@@ -35,7 +35,7 @@ repos:
         stages: [commit]
 
   - repo: https://github.com/returntocorp/semgrep
-    rev: v1.92.0
+    rev: v1.103.0
     hooks:
       - id: semgrep
         args:

CHANGELOG.md

@@ -1,5 +1,19 @@
 # CHANGELOG
 
+## v2.5.0 - 2025-01-30
+
+### Changes
+
+### 🚀 New Features
+
+- Deprecation of v2/orders status endpoint (#161)
+- Not allow empty string for order confirmed business event construct (#160)
+- Add v1/me/business event endpoint (#158)
+
+#### Contributors
+
+@Francois-Gomis, @alma-renovate-bot[bot], @webaaz, [alma-renovate-bot[bot]](https://github.com/apps/alma-renovate-bot) and [github-actions[bot]](https://github.com/apps/github-actions)
+
 ## v2.4.0 - 2024-12-09
 
 ### Changes
@@ -205,6 +219,7 @@
 
 
 
+
   ```
 * Add fields and docs to the Payment entity
 * Add a Refund entity and extract refunds data within the Payment entity constructor

composer.json

@@ -1,7 +1,7 @@
 {
   "name": "alma/alma-php-client",
   "description": "PHP API client for the Alma payments API",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "type": "library",
   "require": {
     "php": "^5.6 || ~7.0 || ~7.1 || ~7.2 || ~7.3 || ~7.4 || ~8.0 || ~8.1 || ~8.2 || ~8.3",

src/Client.php

@@ -30,7 +30,7 @@
 
 class Client
 {
-    const VERSION = '2.4.0';
+    const VERSION = '2.5.0';
 
     const LIVE_MODE = 'live';
     const TEST_MODE = 'test';

src/Endpoints/Merchants.php

@@ -25,8 +25,11 @@
 
 namespace Alma\API\Endpoints;
 
+use Alma\API\Entities\DTO\MerchantBusinessEvent\CartInitiatedBusinessEvent;
+use Alma\API\Entities\DTO\MerchantBusinessEvent\OrderConfirmedBusinessEvent;
 use Alma\API\Entities\FeePlan;
 use Alma\API\Entities\Merchant;
+use Alma\API\Exceptions\RequestException;
 use Alma\API\RequestError;
 
 class Merchants extends Base
@@ -80,4 +83,61 @@ public function feePlans($kind = FeePlan::KIND_GENERAL, $installmentsCounts = "a
             return new FeePlan($val);
         }, $res->json);
     }
+
+    /**
+     * Prepare and send a business event for a cart initiated
+     *
+     * @param CartInitiatedBusinessEvent $cartEventData
+     * @return void
+     * @throws RequestException
+     */
+    public function sendCartInitiatedBusinessEvent(CartInitiatedBusinessEvent $cartEventData)
+    {
+        $cartEventDataPayload = [
+            'event_type' => $cartEventData->getEventType(),
+            'cart_id' => $cartEventData->getCartId()
+        ];
+        $this->sendBusinessEvent($cartEventDataPayload);
+    }
+
+    /**
+     * Prepare and send a business event for Order confirmed
+     *
+     * @param OrderConfirmedBusinessEvent $orderConfirmedBusinessEvent
+     * @return void
+     * @throws RequestException
+     */
+    public function sendOrderConfirmedBusinessEvent(OrderConfirmedBusinessEvent $orderConfirmedBusinessEvent)
+    {
+        $cartEventDataPayload = [
+            'event_type' => $orderConfirmedBusinessEvent->getEventType(),
+            'is_alma_p1x' => $orderConfirmedBusinessEvent->isAlmaP1X(),
+            'is_alma_bnpl' => $orderConfirmedBusinessEvent->isAlmaBNPL(),
+            'was_bnpl_eligible' => $orderConfirmedBusinessEvent->wasBNPLEligible(),
+            'order_id' => $orderConfirmedBusinessEvent->getOrderId(),
+            'cart_id' => $orderConfirmedBusinessEvent->getCartId(),
+            'alma_payment_id' => $orderConfirmedBusinessEvent->getAlmaPaymentId()
+        ];
+        $this->sendBusinessEvent($cartEventDataPayload);
+    }
+
+    /**
+     * Send merchant_business_event and return 204 no content
+     *
+     * @param array $eventData
+     * @return void
+     * @throws RequestException
+     */
+    private function sendBusinessEvent($eventData)
+    {
+        try {
+            $res = $this->request(self::ME_PATH . "/business-events")->setRequestBody($eventData)->post();
+        } catch (RequestError $e) {
+            throw new RequestException($e->getErrorMessage(), null);
+        }
+        if ($res->isError()) {
+            throw new RequestException($res->errorMessage, null, $res);
+        }
+    }
+
 }

src/Endpoints/Orders.php

@@ -133,6 +133,7 @@ public function fetch($orderId)
     }
 
     /**
+     * @deprecated since version 2.5.0 - Use addOrderStatusByMerchantOrderReference() in Payments endpoint
      * @param string $orderExternalId
      * @param array $orderData
      * @return void

src/Entities/DTO/MerchantBusinessEvent/AbstractBusinessEvent.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Alma\API\Entities\DTO\MerchantBusinessEvent;
+
+abstract class AbstractBusinessEvent
+{
+    /**
+     * @var string
+     */
+    protected $eventType;
+
+    /**
+     * Get Event Type for merchant business event
+     *
+     * @return string
+     */
+    public function getEventType()
+    {
+        return $this->eventType;
+    }
+
+}

src/Entities/DTO/MerchantBusinessEvent/CartInitiatedBusinessEvent.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Alma\API\Entities\DTO\MerchantBusinessEvent;
+
+use Alma\API\Exceptions\ParametersException;
+
+class CartInitiatedBusinessEvent extends AbstractBusinessEvent
+{
+    /**
+     * @var string
+     */
+    private $cartId;
+
+    /**
+     * @param string $cartId
+     * @throws ParametersException
+     */
+    public function __construct($cartId)
+    {
+        $this->eventType = 'cart_initiated';
+        if(empty($cartId) || !is_string($cartId)) {
+            throw new ParametersException('CartId must be a string');
+        }
+        $this->cartId = $cartId;
+    }
+
+    /**
+     * Get Cart Id
+     *
+     * @return string
+     */
+    public function getCartId()
+    {
+        return $this->cartId;
+    }
+}

src/Entities/DTO/MerchantBusinessEvent/OrderConfirmedBusinessEvent.php

@@ -0,0 +1,151 @@
+<?php
+
+namespace Alma\API\Entities\DTO\MerchantBusinessEvent;
+
+
+use Alma\API\Exceptions\ParametersException;
+
+class OrderConfirmedBusinessEvent extends AbstractBusinessEvent
+{
+
+    /**
+     * @var bool
+     */
+    private $almaP1XStatus;
+    /**
+     * @var bool
+     */
+    private $almaBNPLStatus;
+    /**
+     * @var bool
+     */
+    private $wasBNPLEligible;
+    /**
+     * @var string
+     */
+    private $orderId;
+    /**
+     * @var string
+     */
+    private $cartId;
+    /**
+     * @var string | null
+     */
+    private $almaPaymentId;
+
+
+    /**
+     * For non alma payment, almaPaymentId should be null
+     * For Alma payment, almaPaymentId should be a string
+     *
+     * @param bool $isAlmaP1X
+     * @param bool $isAlmaBNPL
+     * @param bool $wasBNPLEligible
+     * @param string $orderId
+     * @param string $cartId
+     * @param string | null $almaPaymentId
+     * @throws ParametersException
+     */
+    public function __construct($isAlmaP1X, $isAlmaBNPL, $wasBNPLEligible, $orderId, $cartId, $almaPaymentId = null)
+    {
+        $this->eventType = 'order_confirmed';
+        $this->almaP1XStatus = $isAlmaP1X;
+        $this->almaBNPLStatus = $isAlmaBNPL;
+        $this->wasBNPLEligible = $wasBNPLEligible;
+        $this->orderId = $orderId;
+        $this->cartId = $cartId;
+        $this->almaPaymentId = $almaPaymentId;
+        $this->validateData();
+    }
+
+    /**
+     * @return bool
+     */
+    public function isAlmaP1X()
+    {
+        return $this->almaP1XStatus;
+    }
+
+    /**
+     * @return bool
+     */
+    public function isAlmaBNPL()
+    {
+        return $this->almaBNPLStatus;
+    }
+
+    /**
+     * Was eligible at the time of payment
+     *
+     * @return bool
+     */
+    public function wasBNPLEligible()
+    {
+        return $this->wasBNPLEligible;
+    }
+
+    /**
+     * @return string
+     */
+    public function getOrderId()
+    {
+        return $this->orderId;
+    }
+
+    /**
+     * @return string
+     */
+    public function getCartId()
+    {
+        return $this->cartId;
+    }
+
+    /**
+     * @return string | null
+     */
+    public function getAlmaPaymentId()
+    {
+        return $this->almaPaymentId;
+    }
+
+    /**
+     * Check if it is an Alma payment
+     *
+     * @return bool
+     */
+    public function isAlmaPayment()
+    {
+        return $this->almaP1XStatus || $this->almaBNPLStatus;
+    }
+
+    /**
+     * @return void
+     * @throws ParametersException
+     */
+    protected function validateData()
+    {
+        if(
+            !is_bool($this->almaP1XStatus) ||
+            !is_bool($this->almaBNPLStatus) ||
+            !is_bool($this->wasBNPLEligible) ||
+            (!is_string($this->orderId) || empty($this->orderId)) ||
+            (!is_string($this->cartId) || empty($this->cartId)) ||
+            // Alma payment id should be absent for non Alma payments
+            (!$this->isAlmaPayment() && !is_null($this->almaPaymentId))
+        )
+        {
+            throw new ParametersException('Invalid data type in OrderConfirmedBusinessEvent constructor');
+        }
+
+        //Alma payment id for Alma payment, Must be a string
+        if(
+            $this->isAlmaPayment() &&
+            (!is_string($this->almaPaymentId) || empty($this->almaPaymentId))
+        )
+        {
+            throw new ParametersException('Alma payment id is mandatory for Alma payment');
+        }
+    }
+
+
+}