Rework to add UK VAT validation and improve error reporting (#6)

* Rework to add UK VAT validation and improve error reporting

* Few little tweaks

* Appease the linter gods

* I guess remove this blank import as it seems to be unnecessary

* Few changes based on PR review

* Remove ErrUnexpected since any error we don't handle is unexpected...

Author: chrisrollins65

README.md

@@ -2,11 +2,12 @@ Package vat
 ===
 
 ![Build](https://github.com/Teamwork/vat/actions/workflows/build.yml/badge.svg)
-[![Go Report Card](https://goreportcard.com/badge/github.com/teamwork/vat/v2)](https://goreportcard.com/report/github.com/teamwork/vat/v2)
-[![GoDoc](https://godoc.org/github.com/teamwork/vat/v2?status.svg)](https://godoc.org/github.com/teamwork/vat/v2)
+[![Go Report Card](https://goreportcard.com/badge/github.com/teamwork/vat/v3)](https://goreportcard.com/report/github.com/teamwork/vat/v3)
+[![GoDoc](https://godoc.org/github.com/teamwork/vat/v3?status.svg)](https://godoc.org/github.com/teamwork/vat/v3)
 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/teamwork/vat/master/LICENSE)
 
-Package for validating VAT numbers & retrieving VAT rates (from [ibericode/vat-rates](https://github.com/ibericode/vat-rates)) in Go.
+Package for validating VAT numbers & retrieving VAT rates (
+from [ibericode/vat-rates](https://github.com/ibericode/vat-rates)) in Go.
 
 Based on https://github.com/dannyvankooten/vat
 
@@ -28,28 +29,38 @@ import "github.com/teamwork/vat"
 
 ### Validating VAT numbers
 
-VAT numbers can be validated by format, existence or both. VAT numbers are looked up using the [VIES VAT validation API](http://ec.europa.eu/taxation_customs/vies/).
+VAT numbers can be validated by format, existence or both.
+
+EU VAT numbers are looked up using the [VIES VAT validation API](http://ec.europa.eu/taxation_customs/vies/).
+
+UK VAT numbers are looked up
+using [UK GOV VAT validation API](https://developer.service.hmrc.gov.uk/api-documentation/docs/api/service/vat-registered-companies-api/1.0)
+.
 
 ```go
 package main
 
 import "github.com/teamwork/vat"
 
 func main() {
-  // Validate number by format + existence
-  validity, err := vat.ValidateNumber("NL123456789B01")
+	// These validation functions return an error if the VAT number is invalid. If no error, then it is valid.
+
+	// Validate number by format + existence
+	err := vat.Validate("NL123456789B01")
 
-  // Validate number format
-  validity, err := vat.ValidateNumberFormat("NL123456789B01")
+	// Validate number format
+	err := vat.ValidateFormat("NL123456789B01")
 
-  // Validate number existence
-  validity, err := vat.ValidateNumberExistence("NL123456789B01")
+	// Validate number existence
+	err := vat.ValidateExists("NL123456789B01")
 }
 ```
 
 ### Retrieving VAT rates
 
-> This package relies on a [community maintained repository of vat rates](https://github.com/ibericode/vat-rates). We invite you to toggle notifications for that repository and contribute changes to VAT rates in your country once they are announced.
+> This package relies on a [community maintained repository of vat rates](https://github.com/ibericode/vat-rates). We
+> invite you to toggle notifications for that repository and contribute changes to VAT rates in your country once they
+> are announced.
 
 To get VAT rate periods for a country, first get a CountryRates struct using the country's ISO-3166-1-alpha2 code.
 
@@ -59,16 +70,16 @@ You can get the rate that is currently in effect using the `GetRate` function.
 package main
 
 import (
-  "fmt"
-  "github.com/teamwork/vat"
+	"fmt"
+	"github.com/teamwork/vat"
 )
 
 func main() {
-  c, err := vat.GetCountryRates("IE")
-  r, err := c.GetRate("standard")
+	c, err := vat.GetCountryRates("IE")
+	r, err := c.GetRate("standard")
 
-  fmt.Printf("Standard VAT rate for IE is %.2f", r)
-  // Output: Standard VAT rate for IE is 23.00
+	fmt.Printf("Standard VAT rate for IE is %.2f", r)
+	// Output: Standard VAT rate for IE is 23.00
 }
 ```
 

errors.go

@@ -0,0 +1,28 @@
+package vat
+
+import (
+	"errors"
+	"fmt"
+)
+
+// ErrInvalidVATNumberFormat will be returned if a VAT with an invalid format is given
+var ErrInvalidVATNumberFormat = errors.New("vat: VAT number format is invalid")
+
+// ErrVATNumberNotFound will be returned if the given VAT number is not found in the external lookup service
+var ErrVATNumberNotFound = errors.New("vat: number not found as an existing active VAT number")
+
+// ErrInvalidCountryCode indicates that this package could not find a country matching the VAT number prefix
+var ErrInvalidCountryCode = errors.New("vat: unknown country code")
+
+// ErrInvalidRateLevel will be returned when getting wrong rate level
+var ErrInvalidRateLevel = errors.New("vat: unknown rate level")
+
+// ErrServiceUnavailable will be returned when the service is unreachable
+type ErrServiceUnavailable struct {
+	Err error
+}
+
+// Error returns the error message
+func (e ErrServiceUnavailable) Error() string {
+	return fmt.Sprintf("vat: service is unreachable: %v", e.Err)
+}

gen.go

@@ -0,0 +1,3 @@
+//go:generate mockgen -destination=mocks/mock_lookup_service.go -package=mocks github.com/teamwork/vat/v3 LookupServiceInterface
+
+package vat

go.mod

@@ -1,4 +1,4 @@
-module github.com/teamwork/vat/v2
+module github.com/teamwork/vat/v3
 
 go 1.21