Enhance BusinessNameFromVatID service with improved error handling

- Add Invalid error case to BusinessNameLookupError enum for invalid VAT IDs
- Add label() method to BusinessNameLookupError for human-readable messages
- Pre-validate VAT format before external API calls to avoid unnecessary requests
- Update README documentation to reflect new error handling capabilities

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

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

Author: tanthammar

README.md

@@ -185,7 +185,11 @@ if ($result instanceof BusinessNameLookupError) {
     match ($result) {
         BusinessNameLookupError::Unknown => 'VAT ID not found',
         BusinessNameLookupError::ServiceUnavailable => 'VAT service temporarily unavailable',
+        BusinessNameLookupError::Invalid => 'Invalid VAT ID format',
     };
+    
+    // Or use the built-in label method
+    $errorMessage = $result->label();
 } else {
     // Success - $result is the business name string
     $businessName = $result;

src/Enums/BusinessNameLookupError.php

@@ -6,4 +6,14 @@ enum BusinessNameLookupError: string
 {
     case Unknown = 'unknown';
     case ServiceUnavailable = 'service_unavailable';
+    case Invalid = 'invalid'; //Vat number is invalid, unable to get legal name
+
+    public function label(): string
+    {
+        return match ($this) {
+            self::Unknown => 'Unknown',
+            self::ServiceUnavailable => 'Service Unavailable',
+            self::Invalid => 'Invalid VAT ID',
+        };
+    }
 }

src/Services/BusinessNameFromVatID.php

@@ -5,6 +5,7 @@
 use Mpociot\VatCalculator\Exceptions\VATCheckUnavailableException;
 use Mpociot\VatCalculator\VatCalculator;
 use TantHammar\LaravelRules\Enums\BusinessNameLookupError;
+use TantHammar\LaravelRules\Rules\VatNumberFormat;
 
 class BusinessNameFromVatID
 {
@@ -15,6 +16,12 @@ public static function lookup(string $vatID): object
         }
 
         try {
+
+            //do simple validation before calling external api
+            if (! (new VatNumberFormat)->passes(null, $vatID)) {
+                return BusinessNameLookupError::Invalid;
+            }
+
             // Do not use Facade. Configure VatCalculator to throw an error when country != GB, else only bool false is returned
             $calculator = new VatCalculator(['forward_soap_faults' => true]);