From c0d042743bdcc985e5404a888bc8624e3011c4e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rok=20Su=C5=A1nik?= Date: Wed, 28 Feb 2024 16:46:01 +0100 Subject: [PATCH] Improve readme and update sdk in example (#7) * improve readme and update sdk in example * document url shorthands * remove frontend lib reference --- .github/workflows/ci.yml | 2 +- README.md | 81 ++++++++++++++++++++++++++++++++++++---- example/go.mod | 5 +-- example/go.sum | 2 + 4 files changed, 78 insertions(+), 12 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 23b7e46..2f5df19 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -21,7 +21,7 @@ jobs: - name: Format run: if [ "$(gofmt -s -l . | wc -l)" -gt 0 ]; then exit 1; fi - + - name: vet run: if [ "$(go vet ./... | wc -l)" -gt 0 ]; then exit 1; fi diff --git a/README.md b/README.md index 64c867a..78e67a1 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,100 @@ -# friendly-captcha-go +# Friendly Captcha Go SDK A Go client for the [Friendly Captcha](https://friendlycaptcha.com) service. This client allows for easy integration and verification of captcha responses with the Friendly Captcha API. -> This library is for [Friendly Captcha v2](https://developer.friendlycaptcha.com) only. If you are looking for V1, look [here](https://docs.friendlycaptcha.com) +> This library is for [Friendly Captcha V2](https://developer.friendlycaptcha.com) only. If you are looking for V1, look [here](https://docs.friendlycaptcha.com) ## Installation -**Install using [NPM](https://npmjs.com/)** - ```shell go get github.com/friendlycaptcha/friendly-captcha-go ``` ## Usage -First configure and create a SDK client +Below are some basic examples of how to use the client. + +For a more detailed example, take a look at the [example](./example) directory. + +### Initialization + +```go +import friendlycaptcha "github.com/friendlycaptcha/friendly-captcha-go" +... +opts := []friendlycaptcha.ClientOption{ + friendlycaptcha.WithAPIKey("YOUR_API_KEY"), + friendlycaptcha.WithSitekey("YOUR_SITEKEY"), +} +frcClient, err := friendlycaptcha.NewClient(opts...) +if err != nil { + // handle possible configuration error +} +``` + +### Verifying a Captcha Response + +After calling `VerifyCaptchaResponse` with the captcha response there are two functions on the result object that you should check: + +- `WasAbleToVerify()` indicates whether we were able to verify the captcha response. This will be `false` in case there was an issue with the network/our service or if there was a mistake in the configuration. +- `ShouldAccept()` indicates whether the captcha response was correct. If the client is running in non-strict mode (default) and `WasAbleToVerify()` returned `false`, this will be `true`. + +Below are some examples of this behaviour. + +#### Verifying a correct captcha response without issues when veryfing: + +```go +result := frcClient.VerifyCaptchaResponse(context.TODO(), "CORRECT_CAPTCHA_RESPONSE_HERE") +fmt.Println(result.WasAbleToVerify()) // true +fmt.Println(result.ShouldAccept()) // true +``` + +#### Verifying an incorrect captcha response without issues when veryfing: + +```go +result := frcClient.VerifyCaptchaResponse(context.TODO(), "INCORRECT_CAPTCHA_RESPONSE_HERE") +fmt.Println(result.WasAbleToVerify()) // true +fmt.Println(result.ShouldAccept()) // false +``` + +#### Verifying an incorrect captcha response with issues (network issues or bad configuration) when veryfing in non-strict mode (default): + +```go +result := frcClient.VerifyCaptchaResponse(context.TODO(), "INCORRECT_CAPTCHA_RESPONSE_HERE") +fmt.Println(result.WasAbleToVerify()) // false +fmt.Println(result.ShouldAccept()) // true +``` + +#### Verifying an incorrect captcha response with issues (network/service issues or bad configuration) when veryfing in strict mode: ```go -// TODO: add an example here. +frcClient, _ := friendlycaptcha.NewClient( + ... + friendlycaptcha.WithStrictMode(true), +) +result := frcClient.VerifyCaptchaResponse(context.TODO(), "INCORRECT_CAPTCHA_RESPONSE_HERE") +fmt.Println(result.WasAbleToVerify()) // false +fmt.Println(result.ShouldAccept()) // false ``` +### Configuration + +The client offers several configuration options: + +- **WithAPIKey**: Your Friendly Captcha API key. +- **WithSitekey**: Your Friendly Captcha sitekey. +- **WithStrictMode**: (Optional) In case the client was not able to verify the captcha response at all (for example if there is a network failure or a mistake in configuration), by default the `VerifyCaptchaResponse` returns `True` regardless. By passing `WithStrictMode(true)`, it will return `false` instead: every response needs to be strictly verified. +- **WithSiteverifyEndpoint**: (Optional) The endpoint URL for the site verification API. Shorthands `eu` or `global` are also accepted. Default is `global`. + ## Development ### Run the tests + First run the SDK Test server, then run `go test`. + ```shell docker run -p 1090:1090 friendlycaptcha/sdk-testserver:latest -go test ./... +go test -v -tags=sdkintegration ./... ``` ## License diff --git a/example/go.mod b/example/go.mod index 9deec58..44efd2a 100644 --- a/example/go.mod +++ b/example/go.mod @@ -1,8 +1,5 @@ module github.com/friendlycaptcha/friendly-captcha-go/example -// TODO replace when module is published -replace github.com/friendlycaptcha/friendly-captcha-go => ../ - go 1.18 -require github.com/friendlycaptcha/friendly-captcha-go v0.0.0-00010101000000-000000000000 +require github.com/friendlycaptcha/friendly-captcha-go v0.2.3 diff --git a/example/go.sum b/example/go.sum index 1fdbe10..24bc29d 100644 --- a/example/go.sum +++ b/example/go.sum @@ -1,4 +1,6 @@ github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= +github.com/friendlycaptcha/friendly-captcha-go v0.2.3 h1:BxpIFSfyqDhITry5b41ThYsaIZed+mZnFxr5vwtDrQc= +github.com/friendlycaptcha/friendly-captcha-go v0.2.3/go.mod h1:GxlDhp5cVfyD6zFmrKkAB7pYkVY3HvOM6G9z2pwMRjg= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=