Merge pull request #11 from wneessen/move_example_code_to_testfiles

Move example code to testfiles

README.md

@@ -11,6 +11,5 @@ This Go package provides an simple to use interface to the excellent
 
 
 ## Usage
-Have a look at the [GoDocs Reference](https://pkg.go.dev/github.com/wneessen/go-hibp) for details on how to implement 
+Check out the [GoDocs Reference](https://pkg.go.dev/github.com/wneessen/go-hibp) for details on how to implement 
-access to the HIBP API with this package or check out the examples for the different APIs in the [examples](examples)
+access to the HIBP API with this package. You will also find GoDoc code examples there.
-directory.

breach_test.go

@@ -237,3 +237,73 @@ func TestBreachedAccountWithoutTruncate(t *testing.T) {
 		})
 	}
 }
+
+// ExampleBreachApi_Breaches_getAllBreaches is a code example to show how to fetch all breaches from the
+// HIBP breaches API
+func ExampleBreachApi_Breaches_getAllBreaches() {
+	hc := New()
+	bl, _, err := hc.BreachApi.Breaches()
+	if err != nil {
+		panic(err)
+	}
+	if len(bl) != 0 {
+		for _, b := range bl {
+			fmt.Printf("Found breach:\n\tName: %s\n\tDomain: %s\n\tBreach date: %s\n\n",
+				b.Name, b.Domain, b.BreachDate.Time().Format("Mon, 2. January 2006"))
+		}
+	}
+}
+
+// ExampleBreachApi_Breaches_getAllBreachesNoUnverified is a code example to show how to fetch all breaches from the
+// HIBP breaches API but ignoring unverified breaches
+func ExampleBreachApi_Breaches_getAllBreachesNoUnverified() {
+	hc := New()
+	bl, _, err := hc.BreachApi.Breaches()
+	if err != nil {
+		panic(err)
+	}
+	if len(bl) != 0 {
+		fmt.Printf("Found %d breaches total.\n", len(bl))
+	}
+
+	bl, _, err = hc.BreachApi.Breaches(WithoutUnverified())
+	if err != nil {
+		panic(err)
+	}
+	if len(bl) != 0 {
+		fmt.Printf("Found %d verified breaches total.\n", len(bl))
+	}
+}
+
+// ExampleBreachApi_BreachByName is a code example to show how to fetch a specific breach
+// from the HIBP breaches API using the BreachByName method
+func ExampleBreachApi_BreachByName() {
+	hc := New()
+	bd, _, err := hc.BreachApi.BreachByName("Adobe")
+	if err != nil {
+		panic(err)
+	}
+	if bd != nil {
+		fmt.Println("Details of the 'Adobe' breach:")
+		fmt.Printf("\tDomain: %s\n", bd.Domain)
+		fmt.Printf("\tBreach date: %s\n", bd.BreachDate.Time().Format("2006-01-02"))
+		fmt.Printf("\tAdded to HIBP: %s\n", bd.AddedDate.String())
+	}
+}
+
+// ExampleBreachApi_BreachedAccount is a code example to show how to fetch a list of breaches
+// for a specific site/account from the HIBP breaches API using the BreachedAccount method
+func ExampleBreachApi_BreachedAccount() {
+	apiKey := os.Getenv("HIBP_API_KEY")
+	if apiKey == "" {
+		panic("A API key is required for this API")
+	}
+	hc := New(WithApiKey(apiKey))
+	bd, _, err := hc.BreachApi.BreachedAccount("multiple-breaches@hibp-integration-tests.com")
+	if err != nil {
+		panic(err)
+	}
+	for _, b := range bd {
+		fmt.Printf("Your account was part of the %q breach\n", b.Name)
+	}
+}

examples/breaches-api/all-breaches-nounverified/main.go

@@ -1,25 +0,0 @@
-package main
-
-import (
-	"fmt"
-	"github.com/wneessen/go-hibp"
-)
-
-func main() {
-	hc := hibp.New()
-	bl, _, err := hc.BreachApi.Breaches()
-	if err != nil {
-		panic(err)
-	}
-	if bl != nil && len(bl) != 0 {
-		fmt.Printf("Found %d breaches total.\n", len(bl))
-	}
-
-	bl, _, err = hc.BreachApi.Breaches(hibp.WithoutUnverified())
-	if err != nil {
-		panic(err)
-	}
-	if bl != nil && len(bl) != 0 {
-		fmt.Printf("Found %d verified breaches total.\n", len(bl))
-	}
-}

examples/breaches-api/all-breaches/main.go

@@ -1,20 +0,0 @@
-package main
-
-import (
-	"fmt"
-	"github.com/wneessen/go-hibp"
-)
-
-func main() {
-	hc := hibp.New()
-	bl, _, err := hc.BreachApi.Breaches()
-	if err != nil {
-		panic(err)
-	}
-	if bl != nil && len(bl) != 0 {
-		for _, b := range bl {
-			fmt.Printf("Found breach:\n\tName: %s\n\tDomain: %s\n\tBreach date: %s\n\n",
-				b.Name, b.Domain, b.BreachDate.Time().Format("Mon, 2. January 2006"))
-		}
-	}
-}

examples/breaches-api/breach-by-name/main.go

@@ -1,21 +0,0 @@
-package main
-
-import (
-	"fmt"
-	"github.com/wneessen/go-hibp"
-)
-
-func main() {
-	hc := hibp.New()
-	bd, _, err := hc.BreachApi.BreachByName("Adobe")
-	if err != nil {
-		panic(err)
-	}
-	if bd != nil {
-		fmt.Println("Details of the 'Adobe' breach:")
-		fmt.Printf("\tDomain: %s\n", bd.Domain)
-		fmt.Printf("\tBreach date: %s\n", bd.BreachDate.Time().Format("2006-01-02"))
-		fmt.Printf("\tAdded to HIBP: %s\n", bd.AddedDate.String())
-
-	}
-}

examples/breaches-api/breached-account/main.go

@@ -1,22 +0,0 @@
-package main
-
-import (
-	"fmt"
-	"github.com/wneessen/go-hibp"
-	"os"
-)
-
-func main() {
-	apiKey := os.Getenv("HIBP_API_KEY")
-	if apiKey == "" {
-		panic("A API key is required for this API")
-	}
-	hc := hibp.New(hibp.WithApiKey(apiKey))
-	bd, _, err := hc.BreachApi.BreachedAccount("multiple-breaches@hibp-integration-tests.com")
-	if err != nil {
-		panic(err)
-	}
-	for _, b := range bd {
-		fmt.Printf("Your account was part of the %q breach\n", b.Name)
-	}
-}

examples/pastes-api/pasted-account/main.go

@@ -1,22 +0,0 @@
-package main
-
-import (
-	"fmt"
-	"github.com/wneessen/go-hibp"
-	"os"
-)
-
-func main() {
-	apiKey := os.Getenv("HIBP_API_KEY")
-	if apiKey == "" {
-		panic("A API key is required for this API")
-	}
-	hc := hibp.New(hibp.WithApiKey(apiKey))
-	pd, _, err := hc.PasteApi.PastedAccount("account-exists@hibp-integration-tests.com")
-	if err != nil {
-		panic(err)
-	}
-	for _, p := range pd {
-		fmt.Printf("Your account was part of the %q paste\n", p.Title)
-	}
-}

examples/pwned-password-api/check-password-withpadding/main.go

@@ -1,18 +0,0 @@
-package main
-
-import (
-	"fmt"
-	"github.com/wneessen/go-hibp"
-)
-
-func main() {
-	hc := hibp.New(hibp.WithPwnedPadding())
-	m, _, err := hc.PwnedPassApi.CheckPassword("test")
-	if err != nil {
-		panic(err)
-	}
-	if m != nil && m.Count != 0 {
-		fmt.Printf("Your password with the hash %q was found %d times in the pwned passwords DB\n",
-			m.Hash, m.Count)
-	}
-}

examples/pwned-password-api/check-password/main.go

@@ -1,18 +0,0 @@
-package main
-
-import (
-	"fmt"
-	"github.com/wneessen/go-hibp"
-)
-
-func main() {
-	hc := hibp.New()
-	m, _, err := hc.PwnedPassApi.CheckPassword("test")
-	if err != nil {
-		panic(err)
-	}
-	if m != nil && m.Count != 0 {
-		fmt.Printf("Your password with the hash %q was found %d times in the pwned passwords DB\n",
-			m.Hash, m.Count)
-	}
-}

examples/pwned-password-api/check-sha1/main.go

@@ -1,19 +0,0 @@
-package main
-
-import (
-	"fmt"
-	"github.com/wneessen/go-hibp"
-)
-
-func main() {
-	hc := hibp.New()
-	pwHash := "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3" // represents the PW: "test"
-	m, _, err := hc.PwnedPassApi.CheckSHA1(pwHash)
-	if err != nil {
-		panic(err)
-	}
-	if m != nil && m.Count != 0 {
-		fmt.Printf("Your password with the hash %q was found %d times in the pwned passwords DB\n",
-			m.Hash, m.Count)
-	}
-}

hibp.go

@@ -1,3 +1,4 @@
+// Package hibp provides Go binding to all 3 APIs of the "Have I been Pwned" by Troy Hunt
 package hibp
 
 import (
@@ -12,7 +13,7 @@ import (
 )
 
 // Version represents the version of this package
-const Version = "1.0.1"
+const Version = "1.0.2"
 
 // BaseUrl is the base URL for the majority of API calls
 const BaseUrl = "https://haveibeenpwned.com/api/v3"

password_test.go

@@ -1,6 +1,7 @@
 package hibp
 
 import (
+	"fmt"
 	"testing"
 )
 
@@ -63,3 +64,49 @@ func TestPwnedPasswordHash(t *testing.T) {
 		})
 	}
 }
+
+// ExamplePwnedPassApi_CheckPassword is a code example to show how to check a given password
+// against the HIBP passwords API
+func ExamplePwnedPassApi_CheckPassword() {
+	hc := New()
+	m, _, err := hc.PwnedPassApi.CheckPassword("test")
+	if err != nil {
+		panic(err)
+	}
+	if m != nil && m.Count != 0 {
+		fmt.Printf("Your password with the hash %q was found %d times in the pwned passwords DB\n",
+			m.Hash, m.Count)
+		// Output: Your password with the hash "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3" was found 86453 times in the pwned passwords DB
+	}
+}
+
+// ExamplePwnedPassApi_CheckPassword_withPadding is a code example to show how to check a given password
+// against the HIBP passwords API with the WithPadding() option set
+func ExamplePwnedPassApi_CheckPassword_withPadding() {
+	hc := New(WithPwnedPadding())
+	m, _, err := hc.PwnedPassApi.CheckPassword("test")
+	if err != nil {
+		panic(err)
+	}
+	if m != nil && m.Count != 0 {
+		fmt.Printf("Your password with the hash %q was found %d times in the pwned passwords DB\n",
+			m.Hash, m.Count)
+		// Output: Your password with the hash "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3" was found 86453 times in the pwned passwords DB
+	}
+}
+
+// ExamplePwnedPassApi_CheckSHA1 is a code example to show how to check a given password SHA1 hash
+// against the HIBP passwords API using the CheckSHA1() method
+func ExamplePwnedPassApi_CheckSHA1() {
+	hc := New()
+	pwHash := "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3" // represents the PW: "test"
+	m, _, err := hc.PwnedPassApi.CheckSHA1(pwHash)
+	if err != nil {
+		panic(err)
+	}
+	if m != nil && m.Count != 0 {
+		fmt.Printf("Your password with the hash %q was found %d times in the pwned passwords DB\n",
+			m.Hash, m.Count)
+		// Output: Your password with the hash "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3" was found 86453 times in the pwned passwords DB
+	}
+}

paste_test.go

@@ -1,6 +1,7 @@
 package hibp
 
 import (
+	"fmt"
 	"os"
 	"testing"
 )
@@ -41,3 +42,20 @@ func TestPasteAccount(t *testing.T) {
 		})
 	}
 }
+
+// ExamplePasteApi_PastedAccount is a code example to show how to fetch a specific paste
+// based on its name from the HIBP pastes API using the PastedAccount() method
+func ExamplePasteApi_PastedAccount() {
+	apiKey := os.Getenv("HIBP_API_KEY")
+	if apiKey == "" {
+		panic("A API key is required for this API")
+	}
+	hc := New(WithApiKey(apiKey))
+	pd, _, err := hc.PasteApi.PastedAccount("account-exists@hibp-integration-tests.com")
+	if err != nil {
+		panic(err)
+	}
+	for _, p := range pd {
+		fmt.Printf("Your account was part of the %q paste\n", p.Title)
+	}
+}