BREAKING CHANGE: Refactor BusinessNameFromVatID to return VAT details object instead of translated strings

- Add BusinessNameLookupError enum for error cases (Unknown, ServiceUnavailable)
- BusinessNameFromVatID::lookup() now returns object|BusinessNameLookupError instead of string
- On success: returns full VAT details object with name, address, vatNumber properties
- On error: returns BusinessNameLookupError enum instead of translated error messages
- Update README.md with new usage examples showing error handling patterns

This change provides access to complete VAT information while maintaining clean error handling through enums.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: tanthammar

README.md

@@ -174,9 +174,23 @@ $plusgiro = FakePlusgiro::make();
 ```php
 use TantHammar\LaravelRules\Services\BusinessNameFromVatID;
 use TantHammar\LaravelRules\Services\VatDetailsFromVatID;
-
-// Get business name from VAT ID
-$businessName = BusinessNameFromVatID::lookup('SE556556567801');
+use TantHammar\LaravelRules\Enums\BusinessNameLookupError;
+
+// Get business details from VAT ID
+$result = BusinessNameFromVatID::lookup('SE556556567801');
+
+if ($result instanceof BusinessNameLookupError) {
+    // Handle error cases
+    match ($result) {
+        BusinessNameLookupError::Unknown => 'VAT ID not found',
+        BusinessNameLookupError::ServiceUnavailable => 'VAT service temporarily unavailable',
+    };
+} else {
+    // Success - $result is the VAT details object
+    $businessName = $result->name;
+    $address = $result->address;
+    $vatNumber = $result->vatNumber;
+}
 
 // Get full VAT details
 $details = VatDetailsFromVatID::lookup('SE556556567801');

src/Enums/BusinessNameLookupError.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace TantHammar\LaravelRules\Enums;
+
+enum BusinessNameLookupError: string
+{
+    case Unknown = 'unknown';
+    case ServiceUnavailable = 'service_unavailable';
+}

src/Services/BusinessNameFromVatID.php

@@ -4,15 +4,14 @@
 
 use Mpociot\VatCalculator\Exceptions\VATCheckUnavailableException;
 use Mpociot\VatCalculator\VatCalculator;
+use TantHammar\LaravelRules\Enums\BusinessNameLookupError;
 
 class BusinessNameFromVatID
 {
-    public static function lookup(string $vatID): string
+    public static function lookup(string $vatID): object
     {
-        $unknown = trans('laravel-rules::messages.vat-name-unknown');
-
         if (blank($vatID)) {
-            return $unknown;
+            return BusinessNameLookupError::Unknown;
         }
 
         try {
@@ -21,13 +20,11 @@ public static function lookup(string $vatID): string
 
             $object = $calculator->getVATDetails($vatID);
 
-            return is_object($object) ? $object->name : $unknown;
+            return is_object($object) ? $object : BusinessNameLookupError::Unknown;
 
         } catch (VATCheckUnavailableException $e) {
             //if Country != GB, less verbose messages are returned.
-            return ($message = $e->getMessage()) === "MS_UNAVAILABLE"
-                ? trans('laravel-rules::messages.vies-eu-unavailable')
-                : $message;
+            return BusinessNameLookupError::ServiceUnavailable;
         }
     }
 }