From 08135c4c8f8debef368327fa7386bd3b792a8956 Mon Sep 17 00:00:00 2001
From: Konstantinos Arvanitakis <arvanitakis@radical-elements.com>
Date: Thu, 16 Jul 2026 17:14:41 +0300
Subject: [PATCH] Feature: Creating Shipping Carrier Contracts

---
 .../Contracts/CarrierFulfillmentInterface.php | 24 +++++++++++++++++++
 .../Contracts/SupportsLivePricing.php         | 12 ++++++++++
 .../Contracts/SupportsManifestBatching.php    | 24 +++++++++++++++++++
 3 files changed, 60 insertions(+)
 create mode 100644 src/Shipping/Contracts/CarrierFulfillmentInterface.php
 create mode 100644 src/Shipping/Contracts/SupportsLivePricing.php
 create mode 100644 src/Shipping/Contracts/SupportsManifestBatching.php

diff --git a/src/Shipping/Contracts/CarrierFulfillmentInterface.php b/src/Shipping/Contracts/CarrierFulfillmentInterface.php
new file mode 100644
index 0000000..68f1b30
--- /dev/null
+++ b/src/Shipping/Contracts/CarrierFulfillmentInterface.php
@@ -0,0 +1,24 @@
+<?php
+
+namespace Modules\Core\Shipping\Contracts;
+
+use Lunar\Models\Order;
+use Modules\Core\Shipping\Models\Shipment;
+
+interface CarrierFulfillmentInterface
+{
+    /**
+     * Create a shipment with the carrier for the given order.
+     */
+    public function createShipment(Order $order, array $overrides = []): Shipment;
+
+    /**
+     * Fetch the printable label for a shipment (raw file bytes).
+     */
+    public function printLabel(Shipment $shipment): string;
+
+    /**
+     * Cancel a shipment with the carrier.
+     */
+    public function cancelShipment(Shipment $shipment): void;
+}
diff --git a/src/Shipping/Contracts/SupportsLivePricing.php b/src/Shipping/Contracts/SupportsLivePricing.php
new file mode 100644
index 0000000..ff14a40
--- /dev/null
+++ b/src/Shipping/Contracts/SupportsLivePricing.php
@@ -0,0 +1,12 @@
+<?php
+
+namespace Modules\Core\Shipping\Contracts;
+
+/**
+ * Marker for a Lunar\Shipping\Interfaces\ShippingRateInterface driver that
+ * calculates its price from a live carrier API rather than the manually
+ * configured ShippingRate price/price-breaks. Admin UI uses this to hide
+ * the manual pricing fields for such drivers — carriers without a pricing
+ * API simply don't implement it, and manual pricing remains required.
+ */
+interface SupportsLivePricing {}
diff --git a/src/Shipping/Contracts/SupportsManifestBatching.php b/src/Shipping/Contracts/SupportsManifestBatching.php
new file mode 100644
index 0000000..0ae3718
--- /dev/null
+++ b/src/Shipping/Contracts/SupportsManifestBatching.php
@@ -0,0 +1,24 @@
+<?php
+
+namespace Modules\Core\Shipping\Contracts;
+
+use Illuminate\Support\Collection;
+use Modules\Core\Shipping\DataTransferObjects\ManifestResult;
+
+/**
+ * Optional capability for carriers that batch shipments into a manifest
+ * before courier pickup (e.g. ACS's end-of-day pickup list). Carriers
+ * without this concept simply don't implement it.
+ */
+interface SupportsManifestBatching
+{
+    /**
+     * Shipments created but not yet included in an issued manifest.
+     */
+    public function pendingForManifest(): Collection;
+
+    /**
+     * Finalize the given shipments into a manifest with the carrier.
+     */
+    public function issueManifest(Collection $shipments): ManifestResult;
+}