Feature Add positions DTOs and enhance invoicing

src/Dto/DefaultPositions/AddDefaultPositionDTO.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace CodebarAg\Bexio\Dto\DefaultPositions;
+
+use Exception;
+use Illuminate\Support\Arr;
+use Spatie\LaravelData\Data;
+
+/**
+ * DTO for adding a default (custom) position to a document (invoice, offer, order).
+ * Used in the positions array when creating a document (invoice, offer, order) via the Bexio API.
+ */
+class AddDefaultPositionDTO extends Data
+{
+    public function __construct(
+        public string $amount,
+        public int $unit_id,
+        public int $account_id,
+        public int $tax_id,
+        public string $text,
+        public string $unit_price,
+        public string $discount_in_percent,
+        public string $type = 'KbPositionCustom',
+    ) {}
+
+    public static function fromArray(array $data): self
+    {
+        if (! $data) {
+            throw new Exception('Unable to create DTO. Data missing from response.');
+        }
+
+        return new self(
+            amount: Arr::get($data, 'amount'),
+            unit_id: Arr::get($data, 'unit_id'),
+            account_id: Arr::get($data, 'account_id'),
+            tax_id: Arr::get($data, 'tax_id'),
+            text: Arr::get($data, 'text'),
+            unit_price: Arr::get($data, 'unit_price'),
+            discount_in_percent: Arr::get($data, 'discount_in_percent'),
+            type: Arr::get($data, 'type', 'KbPositionCustom'),
+        );
+    }
+}

src/Dto/DefaultPositions/CreateEditDefaultPositionDTO.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace CodebarAg\Bexio\Dto\DefaultPositions;
+
+use Exception;
+use Illuminate\Support\Arr;
+use Spatie\LaravelData\Data;
+
+/**
+ * DTO for creating or editing a default (custom) position for a document (invoice, offer, order).
+ * Used as the request payload for the kb_position_custom endpoint.
+ */
+class CreateEditDefaultPositionDTO extends Data
+{
+    public function __construct(
+        public string $amount,
+        public int $unit_id,
+        public int $account_id,
+        public int $tax_id,
+        public string $text,
+        public string $unit_price,
+        public string $discount_in_percent,
+        public ?int $parent_id = null,
+    ) {}
+
+    public static function fromArray(array $data): self
+    {
+        if (! $data) {
+            throw new Exception('Unable to create DTO. Data missing from response.');
+        }
+
+        return new self(
+            amount: Arr::get($data, 'amount'),
+            unit_id: Arr::get($data, 'unit_id'),
+            account_id: Arr::get($data, 'account_id'),
+            tax_id: Arr::get($data, 'tax_id'),
+            text: Arr::get($data, 'text'),
+            unit_price: Arr::get($data, 'unit_price'),
+            discount_in_percent: Arr::get($data, 'discount_in_percent'),
+            parent_id: Arr::get($data, 'parent_id'),
+        );
+    }
+}

src/Dto/DefaultPositions/DefaultPositionDTO.php

@@ -0,0 +1,69 @@
+<?php
+
+namespace CodebarAg\Bexio\Dto\DefaultPositions;
+
+use Exception;
+use Illuminate\Support\Arr;
+use Saloon\Http\Response;
+use Spatie\LaravelData\Data;
+
+/**
+ * DTO for representing a default (custom) position as returned by the API.
+ */
+class DefaultPositionDTO extends Data
+{
+    public function __construct(
+        public ?int $id,
+        public ?string $amount,
+        public ?int $unit_id,
+        public ?string $unit_name,
+        public ?int $account_id,
+        public ?int $tax_id,
+        public ?string $tax_value,
+        public ?string $text,
+        public ?string $unit_price,
+        public ?string $discount_in_percent,
+        public ?string $position_total,
+        public ?int $parent_id,
+        public ?string $type,
+        public ?string $pos,
+        public ?string $internal_pos,
+        public ?bool $is_optional,
+    ) {}
+
+    public static function fromResponse(Response $response): self
+    {
+        if ($response->failed()) {
+            throw new Exception('Failed to create DTO from Response');
+        }
+        $data = $response->json();
+
+        return self::fromArray($data);
+    }
+
+    public static function fromArray(array $data): self
+    {
+        if (! $data) {
+            throw new Exception('Unable to create DTO. Data missing from response.');
+        }
+
+        return new self(
+            id: Arr::get($data, 'id'),
+            amount: Arr::get($data, 'amount'),
+            unit_id: Arr::get($data, 'unit_id'),
+            unit_name: Arr::get($data, 'unit_name'),
+            account_id: Arr::get($data, 'account_id'),
+            tax_id: Arr::get($data, 'tax_id'),
+            tax_value: Arr::get($data, 'tax_value'),
+            text: Arr::get($data, 'text'),
+            unit_price: Arr::get($data, 'unit_price'),
+            discount_in_percent: Arr::get($data, 'discount_in_percent'),
+            position_total: Arr::get($data, 'position_total'),
+            parent_id: Arr::get($data, 'parent_id'),
+            type: Arr::get($data, 'type', 'KbPositionCustom'),
+            pos: Arr::get($data, 'pos'),
+            internal_pos: Arr::get($data, 'internal_pos'),
+            is_optional: Arr::get($data, 'is_optional'),
+        );
+    }
+}

src/Dto/DiscountPositions/AddDiscountPositionDTO.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace CodebarAg\Bexio\Dto\DiscountPositions;
+
+use Exception;
+use Illuminate\Support\Arr;
+use Spatie\LaravelData\Data;
+
+/**
+ * DTO for adding a discount position to a document (invoice, offer, order).
+ * Used in the positions array when creating a document (invoice, offer, order) via the Bexio API.
+ */
+class AddDiscountPositionDTO extends Data
+{
+    public function __construct(
+        public string $text,
+        public bool $is_percentual,
+        public string $value,
+        public string $type = 'KbPositionDiscount',
+    ) {}
+
+    public static function fromArray(array $data): self
+    {
+        if (! $data) {
+            throw new Exception('Unable to create DTO. Data missing from response.');
+        }
+
+        return new self(
+            text: Arr::get($data, 'text'),
+            is_percentual: Arr::get($data, 'is_percentual'),
+            value: Arr::get($data, 'value'),
+            type: Arr::get($data, 'type', 'KbPositionDiscount'),
+        );
+    }
+}

src/Dto/DiscountPositions/CreateEditDiscountPositionDTO.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace CodebarAg\Bexio\Dto\DiscountPositions;
+
+use Exception;
+use Illuminate\Support\Arr;
+use Spatie\LaravelData\Data;
+
+/**
+ * DTO for creating or editing a discount position for a document (invoice, offer, order).
+ * Used as the request payload for the kb_position_discount endpoint.
+ */
+class CreateEditDiscountPositionDTO extends Data
+{
+    public function __construct(
+        public string $text,
+        public bool $is_percentual,
+        public string $value,
+        public ?int $parent_id = null,
+    ) {}
+
+    public static function fromArray(array $data): self
+    {
+        if (! $data) {
+            throw new Exception('Unable to create DTO. Data missing from response.');
+        }
+
+        return new self(
+            text: Arr::get($data, 'text'),
+            is_percentual: Arr::get($data, 'is_percentual'),
+            value: Arr::get($data, 'value'),
+            parent_id: Arr::get($data, 'parent_id'),
+        );
+    }
+}

src/Dto/DiscountPositions/DiscountPositionDTO.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace CodebarAg\Bexio\Dto\DiscountPositions;
+
+use Exception;
+use Illuminate\Support\Arr;
+use Saloon\Http\Response;
+use Spatie\LaravelData\Data;
+
+/**
+ * DTO for representing a discount position as returned by the API.
+ */
+class DiscountPositionDTO extends Data
+{
+    public function __construct(
+        public ?int $id,
+        public ?string $text,
+        public ?bool $is_percentual,
+        public ?string $value,
+        public ?string $discount_total,
+        public ?string $type = 'KbPositionDiscount',
+    ) {}
+
+    public static function fromResponse(Response $response): self
+    {
+        if ($response->failed()) {
+            throw new Exception('Failed to create DTO from Response');
+        }
+        $data = $response->json();
+
+        return self::fromArray($data);
+    }
+
+    public static function fromArray(array $data): self
+    {
+        if (! $data) {
+            throw new Exception('Unable to create DTO. Data missing from response.');
+        }
+
+        return new self(
+            id: Arr::get($data, 'id'),
+            text: Arr::get($data, 'text'),
+            is_percentual: Arr::get($data, 'is_percentual'),
+            value: Arr::get($data, 'value'),
+            discount_total: Arr::get($data, 'discount_total'),
+            type: Arr::get($data, 'type', 'KbPositionDiscount'),
+        );
+    }
+}

src/Dto/Invoices/CreateInvoiceDTO.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace CodebarAg\Bexio\Dto\Invoices;
+
+use Exception;
+use Illuminate\Support\Arr;
+use Spatie\LaravelData\Data;
+
+/**
+ * DTO for creating an invoice (request payload).
+ * Positions should be an array of Add*PositionDTOs.
+ */
+class CreateInvoiceDTO extends Data
+{
+    public function __construct(
+        public int $user_id,
+        public int $language_id,
+        public int $bank_account_id,
+        public int $currency_id,
+        public int $payment_type_id,
+        public int $mwst_type,
+        public bool $mwst_is_net,
+        public bool $show_position_taxes,
+        public string $is_valid_from,
+        public string $is_valid_to,
+        public array $positions,
+        public ?string $header,
+        public ?string $footer,
+        public ?string $document_nr = null, // Can not be used if “automatic numbering” is activated in frontend-settings. Required if “automatic numbering” deactivated.
+        public ?string $title = null,
+        public ?int $contact_id = null,
+        public ?int $contact_sub_id = null,
+        public ?int $pr_project_id = null,
+        /** @deprecated */
+        public ?int $logopaper_id = null,
+        public ?string $contact_address_manual = null,
+        public ?string $reference = null,
+        public ?string $api_reference = null,
+        public ?string $template_slug = null,
+    ) {}
+
+    public static function fromArray(array $data): self
+    {
+        if (! $data) {
+            throw new Exception('Unable to create DTO. Data missing from response.');
+        }
+
+        return new self(
+            user_id: Arr::get($data, 'user_id'),
+            language_id: Arr::get($data, 'language_id'),
+            bank_account_id: Arr::get($data, 'bank_account_id'),
+            currency_id: Arr::get($data, 'currency_id'),
+            payment_type_id: Arr::get($data, 'payment_type_id'),
+            header: Arr::get($data, 'header'),
+            footer: Arr::get($data, 'footer'),
+            mwst_type: Arr::get($data, 'mwst_type'),
+            mwst_is_net: Arr::get($data, 'mwst_is_net'),
+            show_position_taxes: Arr::get($data, 'show_position_taxes'),
+            is_valid_from: Arr::get($data, 'is_valid_from'),
+            is_valid_to: Arr::get($data, 'is_valid_to'),
+            positions: Arr::get($data, 'positions', []),
+            document_nr: Arr::get($data, 'document_nr'),
+            title: Arr::get($data, 'title'),
+            contact_id: Arr::get($data, 'contact_id'),
+            contact_sub_id: Arr::get($data, 'contact_sub_id'),
+            pr_project_id: Arr::get($data, 'pr_project_id'),
+            logopaper_id: Arr::get($data, 'logopaper_id'),
+            contact_address_manual: Arr::get($data, 'contact_address_manual'),
+            reference: Arr::get($data, 'reference'),
+            api_reference: Arr::get($data, 'api_reference'),
+            template_slug: Arr::get($data, 'template_slug'),
+        );
+    }
+}