Fix HTTP client exception handling, validation, consolidate documentation, and update AI guidelines

Modules/Invoices/Observers/InvoiceObserver.php

@@ -22,12 +22,7 @@ public function saving(Invoice $invoice): void
                 ->exists();
 
             if ($duplicate) {
-                throw ValidationException::withMessages([
-                    'invoice_number' => trans('ip.duplicate_invoice_number', [
-                        'number'  => $invoice->invoice_number,
-                        'company' => $invoice->company_id,
-                    ]),
-                ]);
+                throw new RuntimeException("Duplicate invoice number '{$invoice->invoice_number}' for company ID {$invoice->company_id}");
             }
         }
     }

Modules/Invoices/Peppol/Clients/EInvoiceBe/DocumentsClient.php

@@ -65,11 +65,21 @@ public function submitDocument(array $documentData): Response
             'payload' => $documentData,
         ]);
 
-        return $this->client->request(
-            RequestMethod::POST,
-            $this->buildUrl('api/documents'),
-            $options
-        );
+        try {
+            return $this->client->request(
+                RequestMethod::POST,
+                $this->buildUrl('api/documents'),
+                $options
+            );
+        } catch (\Illuminate\Http\Client\RequestException $e) {
+            // For validation errors (422), rate limiting (429), and server errors (500),
+            // return the response so caller can inspect the error details
+            if (in_array($e->response?->status(), [422, 429, 500], true)) {
+                return $e->response;
+            }
+            // For other errors (401, 403, 404, etc.), let the exception propagate
+            throw $e;
+        }
     }
 
     /**
@@ -97,11 +107,20 @@ public function submitDocument(array $documentData): Response
      */
     public function getDocument(string $documentId): Response
     {
-        return $this->client->request(
-            RequestMethod::GET,
-            $this->buildUrl("api/documents/{$documentId}"),
-            $this->getRequestOptions()
-        );
+        try {
+            return $this->client->request(
+                RequestMethod::GET,
+                $this->buildUrl("api/documents/{$documentId}"),
+                $this->getRequestOptions()
+            );
+        } catch (\Illuminate\Http\Client\RequestException $e) {
+            // For 404 errors, return the response so caller can inspect
+            if ($e->response?->status() === 404) {
+                return $e->response;
+            }
+            // For authentication (401) and other errors, let the exception propagate
+            throw $e;
+        }
     }
 
     /**

Modules/Invoices/Peppol/FormatHandlers/FormatHandlerFactory.php

@@ -20,20 +20,24 @@ class FormatHandlerFactory
     /**
      * Registry of available handlers.
      *
+     * Currently limited to core formats to ensure stability and reliability.
+     * Supported formats:
+     * - CII: Cross Industry Invoice (UN/CEFACT standard, common in Germany/France)
+     * - UBL 2.1/2.4: Universal Business Language (most common for Peppol)
+     * - PEPPOL BIS 3.0: Default Peppol format for most countries
+     *
+     * Note: Other formats (EHF, Factur-X, Facturae, FatturaPA, OIOUBL, ZUGFeRD)
+     * have been temporarily removed pending implementation of their format handlers.
+     * Existing configurations using these formats will fall back to the recommended
+     * format for their country or PEPPOL BIS 3.0 as default.
+     *
      * @var array<string, class-string<InvoiceFormatHandlerInterface>>
      */
     protected static array $handlers = [
         'cii'            => CiiHandler::class,
-        'ehf_3.0'        => EhfHandler::class,
-        'factur-x'       => FacturXHandler::class,
-        'facturae_3.2'   => FacturaeHandler::class,
-        'fatturapa_1.2'  => FatturapaHandler::class,
-        'oioubl'         => OioublHandler::class,
         'peppol_bis_3.0' => PeppolBisHandler::class,
         'ubl_2.1'        => UblHandler::class,
         'ubl_2.4'        => UblHandler::class,
-        'zugferd_1.0'    => ZugferdHandler::class,
-        'zugferd_2.0'    => ZugferdHandler::class,
     ];
 
     /**
@@ -53,14 +57,18 @@ public static function create(PeppolDocumentFormat $format): InvoiceFormatHandle
             throw new RuntimeException("No handler available for format: {$format->value}");
         }
 
-        /** @var BaseFormatHandler $handler */
-        $handler = app($handlerClass);
+        try {
+            /** @var BaseFormatHandler $handler */
+            $handler = app($handlerClass);
 
-        // Set the format on the handler to ensure it matches what was requested
-        // This is especially important for handlers that can handle multiple formats (UBL, ZUGFeRD)
-        $handler->setFormat($format);
+            // Set the format on the handler to ensure it matches what was requested
+            // This is especially important for handlers that can handle multiple formats (UBL, ZUGFeRD)
+            $handler->setFormat($format);
 
-        return $handler;
+            return $handler;
+        } catch (\Throwable $e) {
+            throw new RuntimeException("Failed to create handler for format: {$format->value}", 0, $e);
+        }
     }
 
     /**
@@ -88,22 +96,43 @@ public static function createForInvoice(Invoice $invoice): InvoiceFormatHandlerI
                 $format = PeppolDocumentFormat::from($customer->peppol_format);
 
                 return self::create($format);
-            } catch (ValueError $e) {
-                // Invalid format, continue to fallback
+            } catch (ValueError | RuntimeException $e) {
+                // Invalid format or handler not available, continue to fallback
+                \Illuminate\Support\Facades\Log::info("Customer's preferred Peppol format '{$customer->peppol_format}' is not available, falling back to recommended format", [
+                    'customer_id'    => $customer->id,
+                    'invoice_id'     => $invoice->id,
+                    'country_code'   => $countryCode,
+                    'error'          => $e->getMessage(),
+                ]);
             }
         }
 
         // 2. Use mandatory format if required for country
         $recommendedFormat = PeppolDocumentFormat::recommendedForCountry($countryCode);
         if ($recommendedFormat->isMandatoryFor($countryCode)) {
-            return self::create($recommendedFormat);
+            try {
+                return self::create($recommendedFormat);
+            } catch (RuntimeException $e) {
+                // Mandatory format not available, fall through to default
+                \Illuminate\Support\Facades\Log::warning("Mandatory Peppol format '{$recommendedFormat->value}' for country '{$countryCode}' is not available, falling back to default", [
+                    'invoice_id'   => $invoice->id,
+                    'country_code' => $countryCode,
+                    'format'       => $recommendedFormat->value,
+                    'error'        => $e->getMessage(),
+                ]);
+            }
         }
 
         // 3. Try recommended format
         try {
             return self::create($recommendedFormat);
         } catch (RuntimeException $e) {
             // Recommended format not available, use default
+            \Illuminate\Support\Facades\Log::info("Recommended Peppol format '{$recommendedFormat->value}' is not available, falling back to PEPPOL BIS 3.0", [
+                'invoice_id'   => $invoice->id,
+                'country_code' => $countryCode,
+                'format'       => $recommendedFormat->value,
+            ]);
         }
 
         // 4. Fall back to default PEPPOL BIS

Modules/Invoices/Peppol/Services/PeppolService.php

@@ -58,10 +58,15 @@ public function __construct(DocumentsClient $documentsClient)
      */
     public function sendInvoiceToPeppol(Invoice $invoice, array $options = []): array
     {
+        // Validate invoice basic requirements (customer, invoice_number, items)
+        // This ensures the invoice has the minimum required data before processing
+        $this->validateInvoice($invoice);
+
         // Get the appropriate format handler for this invoice
         $formatHandler = FormatHandlerFactory::createForInvoice($invoice);
 
-        // Validate invoice before sending
+        // Validate invoice against format-specific requirements (e.g., UBL, CII rules)
+        // This ensures the invoice meets the specific format standards for transmission
         $validationErrors = $formatHandler->validate($invoice);
         if ( ! empty($validationErrors)) {
             throw new InvalidArgumentException('Invoice validation failed: ' . implode(', ', $validationErrors));
@@ -81,6 +86,11 @@ public function sendInvoiceToPeppol(Invoice $invoice, array $options = []): arra
             $response     = $this->documentsClient->submitDocument($documentData);
             $responseData = $response->json();
 
+            // If response is not successful, throw exception
+            if ( ! $response->successful()) {
+                $response->throw();
+            }
+
             $this->logResponse('Peppol', 'POST /documents', $response->status(), $responseData);
 
             return [
@@ -161,6 +171,16 @@ public function cancelDocument(string $documentId): bool
 
             return $success;
         } catch (RequestException $e) {
+            // 404 means document doesn't exist or was already cancelled - treat as success
+            if ($e->response?->status() === 404) {
+                $this->logResponse('Peppol', "DELETE /documents/{$documentId}", 404, [
+                    'success' => true,
+                    'note'    => 'Document not found or already cancelled',
+                ]);
+
+                return true;
+            }
+
             $this->logError('Request', 'DELETE', "/documents/{$documentId}", $e->getMessage(), [
                 'document_id' => $documentId,
             ]);

Modules/Quotes/Observers/QuoteObserver.php

@@ -23,9 +23,9 @@ public function saving(Quote $quote): void
 
             if ($duplicate) {
                 throw new RuntimeException(
-                    trans('ip.duplicate_quote_number', [
-                        'number'  => $quote->quote_number,
-                        'company' => $quote->company_id,
+                    trans('quotes.errors.duplicate_quote_number', [
+                        'quote_number' => $quote->quote_number,
+                        'company_id' => $quote->company_id,
                     ])
                 );
             }