feat: add 2 new methods to order-processing client:

- setOrderParcelPosted
- setOrderParcelPreparation

Author: fatemefallah

docs/services/order_processing.md

@@ -11,15 +11,17 @@ parcels and shipping, generate order statistics, and monitor order status and up
 
 ## Order Processing Methods
 
-| Method                                            | Description          | Parameters                                                                           |
-|---------------------------------------------------|----------------------|--------------------------------------------------------------------------------------|
-| [`getCustomerOrders()`](#get-orders)              | Get orders           | `filters` (OrderFilter)                                                              |
-| [`getCustomerOrder()`](#get-order)                | Get specific order   | `orderId`                                                                            |
-| [`getCustomerOrderItems()`](#get-order-items)     | Get order items      | `filters` (ItemFilter)                                                               |
-| [`getCustomerOrderItem()`](#get-order-item)       | Get specific item    | `itemId`                                                                             |
-| [`getVendorOrdersParcels()`](#get-orders-parcels) | Get orders parcels   | `filters` (OrderParcelFilter)                                                        |
-| [`getOrderParcel()`](#get-order-parcel)           | Get specific parcel  | `parcelId`                                                                           |
-| [`getOrdersStats()`](#get-order-stats)            | Get order statistics | `resourceCount`, `vendorId`, `productId`, `customerId`, `couponCode`, `cacheControl` |
+| Method                                                   | Description          | Parameters                                                                                      |
+|----------------------------------------------------------|----------------------|-------------------------------------------------------------------------------------------------|
+| [`getCustomerOrders()`](#get-orders)                     | Get orders           | `filters?` (OrderFilter)                                                                        |
+| [`getCustomerOrder()`](#get-order)                       | Get specific order   | `orderId`                                                                                       |
+| [`getCustomerOrderItems()`](#get-order-items)            | Get order items      | `filters?` (ItemFilter)                                                                         |
+| [`getCustomerOrderItem()`](#get-order-item)              | Get specific item    | `itemId`                                                                                        |
+| [`getVendorOrdersParcels()`](#get-orders-parcels)        | Get orders parcels   | `filters?` (OrderParcelFilter)                                                                  |
+| [`getOrderParcel()`](#get-order-parcel)                  | Get specific parcel  | `parcelId`                                                                                      |
+| [`setOrderParcelPosted()`](#set-parcel-posted)           | Confirm parcel posted| `parcelId`, `request` (PostedOrderRequest)                                                      |
+| [`setOrderParcelPreparation()`](#set-parcel-preparation) | Confirm parcel preparation | `parcelId`                                                                                |
+| [`getOrdersStats()`](#get-order-stats)                   | Get order statistics | `resourceCount`, `vendorId?`, `productId?`, `customerId?`, `couponCode?`, `cacheControl?`       |
 
 ## Examples
 
@@ -166,20 +168,55 @@ function getOrderParcelExample()
 }
 ```
 
+### Set Parcel Posted
+
+```php
+use Basalam\OrderProcessing\Models\PostedOrderRequest;
+use Basalam\OrderProcessing\Models\ShippingMethodCode;
+
+function setParcelPostedExample()
+{
+    global $client;
+
+    $response = $client->setOrderParcelPosted(
+        parcelId: 789,
+        request: new PostedOrderRequest(
+            shippingMethod: ShippingMethodCode::EXPRESS,
+            trackingCode: 'TRACK123456'
+        )
+    );
+
+    return $response;
+}
+```
+
+### Set Parcel Preparation
+
+```php
+function setParcelPreparationExample()
+{
+    global $client;
+
+    $response = $client->setOrderParcelPreparation(parcelId: 789);
+
+    return $response;
+}
+```
+
 ### Get Order Stats
 
 ```php
 function getOrdersStatsExample()
 {
     global $client;
-    
+
     $stats = $client->getOrdersStats(
         resourceCount: ResourceStats::NUMBER_OF_ORDERS_PER_VENDOR,
-        vendorId: 456,
-        productId: 123,
-        customerId: 789,
-        couponCode: "SAVE10",
-        cacheControl: "no-cache"
+        vendorId: 456,        // Optional
+        productId: 123,       // Optional
+        customerId: 789,      // Optional
+        couponCode: "SAVE10", // Optional
+        cacheControl: "no-cache" // Optional
     );
 
     return $stats;
@@ -211,4 +248,4 @@ Common parcel statuses include:
 
 ## Next Steps
 
-- [Core Service](./core.md) - Manage vendors, products, and users
+- [Core Service](./core.md) - Manage vendors, products, and users

src/Basalam/OrderProcessing/Models/PostedOrderRequest.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace Basalam\OrderProcessing\Models;
+
+use JsonSerializable;
+
+/**
+ * Request model for confirming a parcel as posted.
+ */
+class PostedOrderRequest implements JsonSerializable
+{
+    private int $shippingMethod;
+    private ?string $trackingCode;
+
+    public function __construct(int $shippingMethod, ?string $trackingCode = null)
+    {
+        $this->shippingMethod = $shippingMethod;
+        $this->trackingCode = $trackingCode;
+    }
+
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            $data['shipping_method'],
+            $data['tracking_code'] ?? null
+        );
+    }
+
+    public function toArray(): array
+    {
+        $result = [
+            'shipping_method' => $this->shippingMethod,
+        ];
+
+        if ($this->trackingCode !== null) {
+            $result['tracking_code'] = $this->trackingCode;
+        }
+
+        return $result;
+    }
+
+    public function getShippingMethod(): int
+    {
+        return $this->shippingMethod;
+    }
+
+    public function getTrackingCode(): ?string
+    {
+        return $this->trackingCode;
+    }
+
+    public function jsonSerialize(): mixed
+    {
+        return $this->toArray();
+    }
+}

src/Basalam/OrderProcessing/Models/ResultResponse.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace Basalam\OrderProcessing\Models;
+
+use JsonSerializable;
+
+/**
+ * Generic response wrapper that exposes the result payload from public endpoints.
+ */
+class ResultResponse implements JsonSerializable
+{
+    /**
+     * @var mixed
+     */
+    private mixed $result;
+
+    public function __construct(mixed $result)
+    {
+        $this->result = $result;
+    }
+
+    public static function fromArray(array $data): self
+    {
+        return new self($data['result'] ?? null);
+    }
+
+    public function getResult(): mixed
+    {
+        return $this->result;
+    }
+
+    public function toArray(): array
+    {
+        return ['result' => $this->result];
+    }
+
+    public function jsonSerialize(): array
+    {
+        return $this->toArray();
+    }
+}

src/Basalam/OrderProcessing/Models/ShippingMethodCode.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Basalam\OrderProcessing\Models;
+
+/**
+ * Enum-like class that lists supported shipping method codes.
+ */
+class ShippingMethodCode
+{
+    public const SPECIAL = 3197;
+    public const EXPRESS = 3198;
+    public const COURIER = 3259;
+    public const TRANSIT = 5137;
+    public const TIPAX = 4040;
+    public const MAHEX = 6102;
+    public const CHAPAR = 6101;
+    public const AMADAST = 6110;
+    public const DECA = 6111;
+    public const CHEETA = 6112;
+    public const BOXIT = 6113;
+    public const SALAM_RESAN = 6114;
+}

src/Basalam/OrderProcessing/OrderProcessingService.php

@@ -15,6 +15,8 @@
 use Basalam\OrderProcessing\Models\OrderStatsResponse;
 use Basalam\OrderProcessing\Models\ParcelResponse;
 use Basalam\OrderProcessing\Models\ParcelsResponse;
+use Basalam\OrderProcessing\Models\PostedOrderRequest;
+use Basalam\OrderProcessing\Models\ResultResponse;
 
 /**
  * Client for the Basalam Order Processing Service API.
@@ -165,6 +167,33 @@ public function getOrderParcel(int $parcelId): ParcelResponse
         return ParcelResponse::fromArray($response);
     }
 
+    /**
+     * Confirm that a parcel has been posted.
+     *
+     * @param int $parcelId The parcel ID to update
+     * @param PostedOrderRequest $request Payload that contains shipping method and optional tracking code
+     * @return ResultResponse Result of the operation
+     */
+    public function setOrderParcelPosted(int $parcelId, PostedOrderRequest $request): ResultResponse
+    {
+        $endpoint = "/v1/vendor-parcels/$parcelId/set-posted";
+        $response = $this->post($endpoint, $request->toArray());
+        return ResultResponse::fromArray($response);
+    }
+
+    /**
+     * Confirm that a parcel has entered the preparation phase.
+     *
+     * @param int $parcelId The parcel ID to update
+     * @return ResultResponse Result of the operation
+     */
+    public function setOrderParcelPreparation(int $parcelId): ResultResponse
+    {
+        $endpoint = "/v1/vendor-parcels/$parcelId/set-preparation";
+        $response = $this->post($endpoint);
+        return ResultResponse::fromArray($response);
+    }
+
     /**
      * Get order statistics.
      *
@@ -209,4 +238,4 @@ public function getOrdersStats(
         $response = $this->get($endpoint, $params, $headers);
         return OrderStatsResponse::fromArray($response);
     }
-}
+}

src/Basalam/Version.php

@@ -12,7 +12,7 @@ class Version
     /**
      * SDK version
      */
-    const VERSION = '1.1.4';
+    const VERSION = '1.1.5';
 
     /**
      * SDK name

tests/OrderProcessingServiceTest.php

@@ -10,7 +10,9 @@
 use Basalam\OrderProcessing\Models\OrderFilter;
 use Basalam\OrderProcessing\Models\OrderParcelFilter;
 use Basalam\OrderProcessing\Models\ParcelStatus;
+use Basalam\OrderProcessing\Models\PostedOrderRequest;
 use Basalam\OrderProcessing\Models\ResourceStats;
+use Basalam\OrderProcessing\Models\ShippingMethodCode;
 use PHPUnit\Framework\TestCase;
 
 /**
@@ -313,6 +315,52 @@ public function testGetOrderParcel(): void
         }
     }
 
+    /**
+     * Test confirming a parcel as posted.
+     */
+    public function testSetOrderParcelPosted(): void
+    {
+        try {
+            $request = new PostedOrderRequest(
+                shippingMethod: ShippingMethodCode::SPECIAL,
+                trackingCode: 'TRACKING-CODE-123'
+            );
+
+            $result = $this->basalamClient->setOrderParcelPosted(
+                parcelId: self::TEST_PARCEL_ID,
+                request: $request
+            );
+
+            echo "\n=== Test: Set Vendor Parcel Posted ===\n";
+            echo "Result: " . json_encode($result, JSON_PRETTY_PRINT) . "\n";
+
+            $this->assertNotNull($result);
+        } catch (\Exception $e) {
+            echo "\n=== Test: Set Vendor Parcel Posted ===\n";
+            echo "Error: " . $e->getMessage() . "\n";
+            $this->assertTrue(true);
+        }
+    }
+
+    /**
+     * Test confirming a parcel preparation.
+     */
+    public function testSetOrderParcelPreparation(): void
+    {
+        try {
+            $result = $this->basalamClient->setOrderParcelPreparation(self::TEST_PARCEL_ID);
+
+            echo "\n=== Test: Set Vendor Parcel Preparation ===\n";
+            echo "Result: " . json_encode($result, JSON_PRETTY_PRINT) . "\n";
+
+            $this->assertNotNull($result);
+        } catch (\Exception $e) {
+            echo "\n=== Test: Set Vendor Parcel Preparation ===\n";
+            echo "Error: " . $e->getMessage() . "\n";
+            $this->assertTrue(true);
+        }
+    }
+
     /**
      * Test get orders stats with minimal parameters.
      *
@@ -474,4 +522,4 @@ public function testItemFilterToArrayExcludeNull(): void
         $this->assertNotNull($filter);
     }
 
-}
+}