HP-2883: Implement Business Central bills import service

src/action/AbstractAction.php

@@ -68,9 +68,9 @@
         QuantityInterface $quantity,
         CustomerInterface $customer,
         DateTimeImmutable $time,
-        SaleInterface $sale = null,
-        ActionState $state = null,
-        ActionInterface $parent = null,
+        ?SaleInterface $sale = null,
+        ?ActionState $state = null,
+        ?ActionInterface $parent = null,
         float $fractionOfMonth = 0.0
     ) {
         $this->id       = $id;
@@ -89,7 +89,7 @@
      * Provides unique string.
      * Can be used to compare or aggregate actions.
      */
     public function getUniqueString(): string
     {
         $parts = [
             'buyer'     => $this->customer->getUniqueId(),
@@ -157,7 +157,7 @@
         return $this->time;
     }
 
     public function setTime(DateTimeImmutable $time)
     {
         $this->time = $time;
     }
@@ -167,7 +167,7 @@
         return $this->state;
     }
 
     public function setFinished(): void
     {
         $this->state = ActionState::finished();
     }
@@ -188,7 +188,7 @@
     /**
      * {@inheritdoc}
      */
     public function hasParent()
     {
         return $this->parent !== null;
     }
@@ -198,7 +198,7 @@
         return $this->id !== null;
     }
 
     public function setId($id)
     {
         if ((string) $this->id === (string) $id) {
             return;

src/bill/Bill.php

@@ -67,17 +67,29 @@ class Bill implements BillInterface
     /** @var UsageInterval */
     protected $usageInterval;
 
+    /** @var BillSource|null */
+    protected $source;
+
+    /** @var BillTxn|null */
+    protected $txn;
+
+    /** @var BillReversesId|null */
+    protected $reversesId;
+
     public function __construct(
                             $id,
         TypeInterface $type,
         DateTimeImmutable $time,
         Money $sum,
         QuantityInterface $quantity,
         CustomerInterface $customer,
-        TargetInterface $target = null,
-        PlanInterface $plan = null,
+        ?TargetInterface $target = null,
+        ?PlanInterface $plan = null,
         array $charges = [],
-        BillState $state = null
+        ?BillState $state = null,
+        ?BillSource $source = null,
+        ?BillTxn $txn = null,
+        ?BillReversesId $reversesId = null,
     ) {
         $this->id           = $id;
         $this->type         = $type;
@@ -89,6 +101,9 @@ public function __construct(
         $this->plan         = $plan;
         $this->charges      = $charges;
         $this->state        = $state;
+        $this->source       = $source;
+        $this->txn          = $txn;
+        $this->reversesId   = $reversesId;
     }
 
     /**
@@ -242,6 +257,16 @@ public function getComment()
         return $this->comment;
     }
 
+    public function getSource(): ?BillSource
+    {
+        return $this->source;
+    }
+
+    public function getTxn(): ?BillTxn
+    {
+        return $this->txn;
+    }
+
     public function setComment(string $comment)
     {
         $this->comment = $comment;
@@ -256,4 +281,18 @@ public function setUsageInterval(UsageInterval $usageInterval): void
     {
         $this->usageInterval = $usageInterval;
     }
+
+    public function getReversesId(): ?BillReversesId
+    {
+        return $this->reversesId;
+    }
+
+    /**
+     * @param BillReversesId|null $reversesId
+     * @return void
+     */
+    public function setReversesId($reversesId): void
+    {
+        $this->reversesId = $reversesId;
+    }
 }

src/bill/BillInterface.php

@@ -55,4 +55,10 @@ public function getCharges();
     public function getUsageInterval(): UsageInterval;
 
     public function setUsageInterval(UsageInterval $usageInterval): void;
+
+    public function getSource(): ?BillSource;
+
+    public function getTxn(): ?BillTxn;
+
+    public function getReversesId(): ?BillReversesId;
 }

src/bill/BillRequisite.php

@@ -9,7 +9,7 @@ class BillRequisite
 
     protected ?string $name = null;
 
-    public function __construct($id = null, string $name = null)
+    public function __construct($id = null, ?string $name = null)
     {
         $this->id = $id;
         $this->name = $name;

src/bill/BillReversesId.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace hiqdev\php\billing\bill;
+
+class BillReversesId
+{
+    /** @var int|null */
+    protected $id;
+
+    public function __construct($id = null)
+    {
+        $this->id = $id;
+    }
+
+    public function getId(): int
+    {
+        return $this->id;
+    }
+
+    public static function fromInt(int $id): self
+    {
+        return new self($id);
+    }
+}

src/bill/BillSource.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace hiqdev\php\billing\bill;
+
+class BillSource
+{
+    /** @var int|string|null */
+    protected $id;
+
+    protected ?string $name = null;
+
+    public function __construct($id = null, ?string $name = null)
+    {
+        $this->id = $id;
+        $this->name = $name;
+    }
+
+    public function getId()
+    {
+        return $this->id;
+    }
+
+    public function getName(): ?string
+    {
+        return $this->name;
+    }
+}

src/bill/BillTxn.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace hiqdev\php\billing\bill;
+
+/**
+ * BillTxn
+ *
+ * Represents an immutable external payment transaction identifier.
+ *
+ * A TransactionId uniquely identifies a financial transaction
+ * as defined by an external payment or accounting system
+ * (e.g. Business Central, merchant gateways, banks).
+ *
+ * This value:
+ * - Is created by an external system, never generated internally
+ * - Is stable across retries, webhooks, and re-imports
+ * - Is used for idempotency and reconciliation
+ * - Has meaning outside of the database and application boundaries
+ *
+ * Uniqueness is guaranteed only within the scope of a source system
+ * (see Source / external system).
+ *
+ * Typical examples:
+ * - UUIDs
+ * - Gateway transaction references
+ * - Accounting document numbers
+ */
+class BillTxn
+{
+    /** @var int|string|null */
+    protected $value;
+
+    public function __construct($txn = null)
+    {
+        $this->value = $txn;
+    }
+
+    public function getValue()
+    {
+        return $this->value;
+    }
+
+    public static function fromString(string $txn): self
+    {
+        return new self($txn);
+    }
+}

src/charge/Charge.php

@@ -72,7 +72,7 @@ public function __construct(
         ?PriceInterface $price,
         QuantityInterface $usage,
         Money $sum,
-        BillInterface $bill = null
+        ?BillInterface $bill = null
     ) {
         $this->id       = $id;
         $this->type     = $type;

src/charge/modifiers/Installment.php

@@ -39,7 +39,7 @@ public function buildPrice(Money $sum)
         $target = $this->getTarget();
         $prepaid = Quantity::create('items', 0);
 
-        return new SinglePrice(null, $type, $target, null, $prepaid, $sum);
+        return new SinglePrice(null, $type, $target, $prepaid, $sum);
     }
 
     public function getType()

src/customer/Customer.php

@@ -37,7 +37,7 @@ class Customer implements CustomerInterface
      */
     protected $sellers = [];
 
-    public function __construct($id, $login, CustomerInterface $seller = null)
+    public function __construct($id, $login, ?CustomerInterface $seller = null)
     {
         $this->id = $id;
         $this->login = $login;

src/plan/Plan.php

@@ -57,9 +57,9 @@ class Plan implements PlanInterface
     public function __construct(
         $id,
         $name,
-        CustomerInterface $seller = null,
+        ?CustomerInterface $seller = null,
         $prices = [],
-        TypeInterface $type = null,
+        ?TypeInterface $type = null,
         $parent_id = null
     ) {
         $this->id = $id;

src/price/AbstractPrice.php

@@ -56,7 +56,7 @@ public function __construct(
         $id,
         TypeInterface $type,
         TargetInterface $target,
-        PlanInterface $plan = null
+        ?PlanInterface $plan = null
     ) {
         $this->id = $id;
         $this->type = $type;

src/price/PriceFactory.php

@@ -89,7 +89,7 @@ public function createRatePrice(PriceCreationDto $dto)
 
     public function createSinglePrice(PriceCreationDto $dto)
     {
-        return new SinglePrice($dto->id, $dto->type, $dto->target, $dto->plan, $dto->prepaid, $dto->price);
+        return new SinglePrice($dto->id, $dto->type, $dto->target, $dto->prepaid, $dto->price, $dto->plan);
     }
 
     public function createProgressivePrice(PriceCreationDto $dto): ProgressivePrice

src/price/SinglePrice.php

@@ -36,9 +36,9 @@ public function __construct(
         $id,
         TypeInterface $type,
         TargetInterface $target,
-        PlanInterface $plan = null,
         QuantityInterface $prepaid,
-        Money $price
+        Money $price,
+        ?PlanInterface $plan = null,
     ) {
         parent::__construct($id, $type, $target, $plan);
         $this->prepaid  = $prepaid;

src/product/price/PriceTypeDefinitionCollection.php

@@ -31,7 +31,7 @@ public function __construct(
          */
         private readonly TariffTypeDefinitionInterface $parent,
         private readonly PriceTypeDefinitionFactoryInterface $factory,
-        PriceTypeDefinitionCollectionInterface $collectionInstance = null,
+        ?PriceTypeDefinitionCollectionInterface $collectionInstance = null,
     ) {
         $this->storage = new PriceTypeStorage();
         $this->collectionInstance = $collectionInstance ?? $this;

tests/behat/bootstrap/FeatureContext.php

@@ -100,7 +100,7 @@ public function priceIs($target, $type, $sum, $currency, $unit, $quantity = 0)
         $target = new Target(Target::ANY, $target);
         $quantity = Quantity::create($unit, $quantity);
         $sum = $this->moneyParser->parse($sum, new Currency($currency));
-        $this->setPrice(new SinglePrice(null, $type, $target, null, $quantity, $sum));
+        $this->setPrice(new SinglePrice(null, $type, $target, $quantity, $sum));
     }
 
     protected array $progressivePrice = [];

tests/unit/action/ActionTest.php

@@ -87,7 +87,7 @@ protected function setUp(): void
         $this->target   = new Target(2, 'server');
         $this->prepaid  = Quantity::gigabyte(1);
         $this->money    = Money::USD(10000);
-        $this->price    = new SinglePrice(5, $this->type, $this->target, null, $this->prepaid, $this->money);
+        $this->price    = new SinglePrice(5, $this->type, $this->target, $this->prepaid, $this->money);
         $this->customer = new Customer(2, 'client');
         $this->time     = new DateTimeImmutable('now');
         $this->generalizer = new Generalizer();

tests/unit/charge/modifiers/InstallmentTest.php

@@ -30,7 +30,7 @@ protected function setUp(): void
     {
         parent::setUp();
         $this->type = Type::anyId('monthly,installment');
-        $this->price = new SinglePrice(5, $this->type, $this->target, null, $this->prepaid, $this->money);
+        $this->price = new SinglePrice(5, $this->type, $this->target, $this->prepaid, $this->money);
     }
 
     protected function buildInstallment($term)

tests/unit/charge/modifiers/OnceTest.php

@@ -37,7 +37,7 @@ private function createType(string $name): TypeInterface
 
     private function createPrice(TypeInterface $type): PriceInterface
     {
-        return new SinglePrice(5, $type, $this->target, null, $this->prepaid, $this->money);
+        return new SinglePrice(5, $type, $this->target, $this->prepaid, $this->money);
     }
 
     #[\PHPUnit\Framework\Attributes\DataProvider('periodCreationProvider')]

tests/unit/price/SinglePriceTest.php

@@ -40,7 +40,7 @@ protected function setUp(): void
         $this->type     = new Type(null, 'server_traf');
         $this->quantity = Quantity::gigabyte(10);
         $this->money    = Money::USD(15);
-        $this->price    = new SinglePrice(null, $this->type, $this->target, null, $this->quantity, $this->money);
+        $this->price    = new SinglePrice(null, $this->type, $this->target, $this->quantity, $this->money);
     }
 
     protected function tearDown(): void