friendlycaptcha

package module
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 24, 2026 License: MIT Imports: 9 Imported by: 1

README

Friendly Captcha Go SDK

A Go client for the Friendly Captcha service. This client allows for easy integration and verification of captcha responses and retrieval of risk intelligence data with the Friendly Captcha API.

This library is for Friendly Captcha V2 only. If you are looking for V1, look here

Installation

go get github.com/friendlycaptcha/friendly-captcha-go

Usage

Below are basic examples of how to use the client.

For a more detailed end-to-end example (captcha verification + risk intelligence retrieval in one app), take a look at the example directory.

Initialization
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
}
Captcha Verification

Use VerifyCaptchaResponse for the captcha flow via the siteverify endpoint (/api/v2/captcha/siteverify).

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:
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:
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):
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:
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
Risk Intelligence Data Retrieval

Call RetrieveRiskIntelligence to retrieve risk intelligence data from a token via the retrieve endpoint (/api/v2/riskIntelligence/retrieve).

result := frcClient.RetrieveRiskIntelligence(context.TODO(), "RISK_INTELLIGENCE_TOKEN_HERE")
if !result.WasAbleToRetrieve() {
    // handle request/client error, inspect result.RequestError()
    return
}
if !result.IsValid() {
    // handle invalid token, inspect result.Response().Error
    return
}
// The risk intelligence data is available in result.Response().Data.
data := result.Response().Data.RiskIntelligence
Configuration

The client offers several configuration options:

  • WithAPIKey: Your Friendly Captcha API key.
  • WithSitekey: (Optional) Your Friendly Captcha sitekey. Configure this if you want to ensure that a captcha solution or risk intelligence token was generated from a specific 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.
  • WithAPIEndpoint: (Optional) The base API endpoint (used for both captcha verification and risk intelligence retrieval). Shorthands eu or global are also accepted. Default is global.

Development

Run the tests

First run the SDK Test server, then run go test.

docker run -p 1090:1090 friendlycaptcha/sdk-testserver:latest

go test -v -tags=sdkintegration ./...

License

Open source under MIT.

Documentation

Index

Constants

View Source 
const ResponseFormFieldName = "frc-captcha-response"

The name of the form field that, by default, the widget will put the captcha response in.

Variables

View Source 
var ErrCreatingRiskIntelligenceRetrieveRequest = errors.New("could not create risk intelligence retrieve request body")

Could not create the request body (i.e. JSON marshal it), this should never happen.

View Source 
var ErrCreatingVerificationRequest = errors.New("could not create verification request body")

Could not create the request body (i.e. JSON marshal it), this should never happen but if it does then probably the captcha solution value is really weird - let's not accept the verification.

View Source 
var ErrRiskIntelligenceRetrieveFailedDueToClientError = errors.New(
	"risk intelligence retrieve request failed due to a client error (check your credentials)",
)

This error signifies a non-200 response from the server. Usually this means that your API key was wrong.

View Source 
var ErrRiskIntelligenceRetrieveRequest = errors.New("risk intelligence retrieve request failed talking to Friendly Captcha API")

The POST request to the Friendly Captcha API could not be completed for some reason.

View Source 
var ErrVerificationFailedDueToClientError = errors.New(
	"verification request failed due to a client error (check your credentials)",
)

This error signifies a non-200 response from the server. Usually this means that your API key was wrong. You should notify yourself if this happens, but it's usually still a good idea to accept the captcha even though we were unable to verify it: we don't want to lock users out.

View Source 
var ErrVerificationRequest = errors.New("verification request failed talking to Friendly Captcha API")

The POST request to the Friendly Captcha API could not be completed for some reason.

View Source 
var Version = "0.4.1"

Functions

This section is empty.

Types

type Client 

type Client struct {
	APIKey      string
	Sitekey     string
	APIEndpoint string
	// If Strict is set to true only strictly verified captcha response will be allowed.
	// For example: if your server can not reach the Friendly Captcha endpoint, it will still advise to accept the response
	// regardless.
	//
	// By default Strict is false: `ShouldAccept()` will return true when for instance the Friendly Captcha API
	// could not be reached.
	Strict bool
	// The HTTP client to use for making requests to the Friendly Captcha API.
	// Defaults to `http.DefaultClient`
	HTTPClient *http.Client
}

A client for the Friendly Captcha API, see also the API docs at https://developer.friendlycaptcha.com

func NewClient 

func NewClient(opts ...ClientOption) (*Client, error)

NewClient creates a new Friendly Captcha client with the given options.

func (*Client) RetrieveRiskIntelligence added in v0.4.0 

func (frc *Client) RetrieveRiskIntelligence(ctx context.Context, token string) RiskIntelligenceRetrieveResult

RetrieveRiskIntelligence takes a risk intelligence token and retrieves the associated risk intelligence data from the Friendly Captcha API. It returns a RiskIntelligenceRetrieveResult, which contains the risk intelligence data.

func (*Client) VerifyCaptchaResponse added in v0.2.0 

func (frc *Client) VerifyCaptchaResponse(ctx context.Context, captchaResponse string) VerifyResult

VerifyCaptchaResponse takes a captcha response and verifies it with the Friendly Captcha API. It returns a VerifyResult, which contains the result of the verification.

On this result struct that will allow you to check if the verification could be performed, and whether you should allow the user to proceed.

type ClientAutomationData added in v0.3.0 

type ClientAutomationData struct {
	// AutomationTool contains detected automation tool information.
	AutomationTool ClientAutomationToolData `json:"automation_tool"`

	// KnownBot contains detected known bot information.
	KnownBot ClientAutomationKnownBotData `json:"known_bot"`
}

ClientAutomationData contains information about detected automation.

Available when the Bot Detection module is enabled. Null when the Bot Detection module is not enabled.

type ClientAutomationKnownBotData added in v0.3.0 

type ClientAutomationKnownBotData struct {
	// Detected indicates whether a known bot was detected.
	Detected bool `json:"detected"`

	// ID is the bot identifier. Empty if no bot detected.
	// Example: "googlebot", "bingbot", "chatgpt"
	ID string `json:"id"`

	// Name is the human-readable bot name. Empty if no bot detected.
	// Example: "Googlebot", "Bingbot", "ChatGPT"
	Name string `json:"name"`

	// Type is the bot type classification. Empty if no bot detected.
	Type string `json:"type"`

	// URL is the link to bot documentation. Empty if no bot detected.
	// Example: "https://developers.google.com/search/docs/crawling-indexing/googlebot"
	URL string `json:"url"`
}

ClientAutomationKnownBotData contains detected known bot details.

type ClientAutomationToolData added in v0.3.0 

type ClientAutomationToolData struct {
	// Detected indicates whether an automation tool was detected.
	Detected bool `json:"detected"`

	// ID is the automation tool identifier. Empty if no tool detected.
	// Example: "puppeteer", "selenium", "playwright"
	ID string `json:"id"`

	// Name is the human-readable tool name. Empty if no tool detected.
	// Example: "Puppeteer", "Selenium WebDriver", "Playwright"
	Name string `json:"name"`

	// Type is the automation tool type. Empty if no tool detected.
	Type string `json:"type"`
}

ClientAutomationToolData contains detected automation tool details.

type ClientBrowserData added in v0.3.0 

type ClientBrowserData struct {
	// ID is the unique browser identifier. Empty string if browser could not be identified.
	// Example: "firefox", "chrome", "chrome_android", "edge", "safari", "safari_ios", "webview_ios"
	ID string `json:"id"`

	// Name is the human-readable browser name. Empty string if browser could not be identified.
	// Example: "Firefox", "Chrome", "Edge", "Safari", "Safari on iOS", "WebView on iOS"
	Name string `json:"name"`

	// Version is the browser version name. Assumed to be the most recent release matching the signature if exact version unknown. Empty if unknown.
	// Example: "146.0" or "16.5"
	Version string `json:"version"`

	// ReleaseDate is the release date of the browser version in "YYYY-MM-DD" format. Empty string if unknown.
	// Example: "2026-01-28"
	ReleaseDate string `json:"release_date"`
}

ClientBrowserData contains detected browser details.

Available when the Browser Identification module is enabled. Null when the Browser Identification module is not enabled.

type ClientBrowserEngineData added in v0.3.0 

type ClientBrowserEngineData struct {
	// ID is the unique rendering engine identifier. Empty string if engine could not be identified.
	// Example: "gecko", "blink", "webkit"
	ID string `json:"id"`

	// Name is the human-readable engine name. Empty string if engine could not be identified.
	// Example: "Gecko", "Blink", "WebKit"
	Name string `json:"name"`

	// Version is the rendering engine version. Assumed to be the most recent release matching the signature if exact version unknown. Empty if unknown.
	// Example: "146.0" or "16.5"
	Version string `json:"version"`
}

ClientBrowserEngineData contains detected rendering engine details.

Available when the Browser Identification module is enabled. Null when the Browser Identification module is not enabled.

type ClientData added in v0.3.0 

type ClientData struct {
	// HeaderUserAgent is the User-Agent HTTP header value.
	// Example: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:146.0) Gecko/20100101 Firefox/146.0"
	HeaderUserAgent string `json:"header_user_agent"`

	// TimeZone contains time zone information.
	//
	// Available when the Browser Identification module is enabled.
	// Null when the Browser Identification module is not enabled.
	TimeZone null.Value[ClientTimeZoneData] `json:"time_zone"`

	// Browser information.
	//
	// Available when the Browser Identification module is enabled.
	// Null when the Browser Identification module is not enabled.
	Browser null.Value[ClientBrowserData] `json:"browser"`

	// BrowserEngine information.
	//
	// Available when the Browser Identification module is enabled.
	// Null when the Browser Identification module is not enabled.
	BrowserEngine null.Value[ClientBrowserEngineData] `json:"browser_engine"`

	// Device information.
	//
	// Available when the Browser Identification module is enabled.
	// Null when the Browser Identification module is not enabled.
	Device null.Value[ClientDeviceData] `json:"device"`

	// OS information.
	//
	// Available when the Browser Identification module is enabled.
	// Null when the Browser Identification module is not enabled.
	OS null.Value[ClientOSData] `json:"os"`

	// TLSSignature contains TLS signatures.
	//
	// Available when the Bot Detection module is enabled.
	// Null when the Bot Detection module is not enabled.
	TLSSignature null.Value[TLSSignatureData] `json:"tls_signature"`

	// Automation contains automation detection data.
	//
	// Available when the Bot Detection module is enabled.
	// Null when the Bot Detection module is not enabled.
	Automation null.Value[ClientAutomationData] `json:"automation"`
}

ClientData contains information about the user agent and device.

type ClientDeviceData added in v0.3.0 

type ClientDeviceData struct {
	// Type is the device type.
	// Example: "desktop", "mobile", "tablet"
	Type string `json:"type"`

	// Brand is the device brand.
	// Example: "Apple", "Samsung", "Google"
	Brand string `json:"brand"`

	// Model is the device model name.
	// Example: "iPhone 17", "Galaxy S21 (SM-G991B)", "Pixel 10"
	Model string `json:"model"`
}

ClientDeviceData contains detected device details.

Available when the Browser Identification module is enabled. Null when the Browser Identification module is not enabled.

type ClientOSData added in v0.3.0 

type ClientOSData struct {
	// ID is the unique operating system identifier. Empty string if OS could not be identified.
	// Example: "windows", "macos", "ios", "android", "linux"
	ID string `json:"id"`

	// Name is the human-readable operating system name. Empty string if OS could not be identified.
	// Example: "Windows", "macOS", "iOS", "Android", "Linux"
	Name string `json:"name"`

	// Version is the operating system version.
	// Example: "10", "11.2.3", "14.4"
	Version string `json:"version"`
}

ClientOSData contains detected OS details.

Available when the Browser Identification module is enabled. Null when the Browser Identification module is not enabled.

type ClientOption added in v0.2.0 

type ClientOption func(*Client) error

A ClientOption is a function that can be passed to NewClient to configure a new Client.

func WithAPIEndpoint added in v0.3.0 

func WithAPIEndpoint(apiEndpoint string) ClientOption

WithAPIEndpoint sets the API endpoint domain for the client. Takes a domain without path (e.g., "https://global.frcapi.com"), or the shorthands "global" or "eu".

func WithAPIKey added in v0.2.0 

func WithAPIKey(apiKey string) ClientOption

WithAPIKey sets the API key for the client.

func WithSitekey added in v0.2.0 

func WithSitekey(sitekey string) ClientOption

WithSitekey sets the sitekey for the client. This is optional.

func WithSiteverifyEndpoint added in v0.2.0 

func WithSiteverifyEndpoint(siteverifyEndpoint string) ClientOption

WithSiteverifyEndpoint sets the API endpoint for the client. Deprecated: Use WithAPIEndpoint instead. This function strips the path from the URL and calls WithAPIEndpoint. Takes a full URL, or the shorthands "global" or "eu".

func WithStrictMode added in v0.2.0 

func WithStrictMode(strict bool) ClientOption

In strict mode only strictly verified captcha response are allowed. If your API key is invalid or your server can not reach the API endpoint all requests will be rejected.

This defaults to `false`.

type ClientTimeZoneData added in v0.3.0 

type ClientTimeZoneData struct {
	// Name is the IANA time zone name reported by the browser.
	// Example: "America/New_York" or "Europe/Berlin"
	Name string `json:"name"`

	// CountryISO2 is the two-letter ISO 3166-1 alpha-2 country code derived from the time zone.
	// "XU" if timezone is missing or cannot be mapped to a country (e.g., "Etc/UTC").
	// Example: "US" or "DE"
	CountryISO2 string `json:"country_iso2"`
}

ClientTimeZoneData contains IANA time zone data.

Available when the Browser Identification module is enabled. Null when the Browser Identification module is not enabled.

type ErrorCode added in v0.2.0 

type ErrorCode string

ErrorCode is an error code that the Friendly Captcha API can return. 

const (
	// (401) You forgot to set the X-API-Key header.
	ErrorCodeAuthRequired ErrorCode = "auth_required"
	// (401) The API key you provided is invalid.
	ErrorCodeAuthInvalid ErrorCode = "auth_invalid"
	// (400) The sitekey in your request is invalid.
	ErrorCodeSitekeyInvalid ErrorCode = "sitekey_invalid"
	// (400) The response field is missing in your request.
	ErrorCodeResponseMissing ErrorCode = "response_missing"
	// (400) The risk intelligence token is missing in your request.
	ErrorCodeTokenMissing ErrorCode = "token_missing"
	// (200) The risk intelligence token has expired.
	ErrorCodeTokenExpired ErrorCode = "token_expired"
	// (200) The risk intelligence token is invalid.
	ErrorCodeTokenInvalid ErrorCode = "token_invalid"

	// (200) The response field is invalid.
	ErrorCodeResponseInvalid ErrorCode = "response_invalid"
	// (200) The response has expired.
	ErrorCodeResponseTimeout ErrorCode = "response_timeout"
	// (200) The response has already been used.
	ErrorCodeResponseDuplicate ErrorCode = "response_duplicate"

	// (400) Something else is wrong with your request, e.g. the request body was empty.
	ErrorCodeBadRequest ErrorCode = "bad_request"
)

type NetworkAbuseContactData added in v0.3.0 

type NetworkAbuseContactData struct {
	// Address is the postal address of the abuse contact.
	// Example: "Vodafone GmbH, Campus Eschborn, Duesseldorfer Strasse 15, D-65760 Eschborn, Germany"
	Address string `json:"address"`

	// Name of the abuse contact person or team.
	// Example: "Vodafone Germany IP Core Backbone"
	Name string `json:"name"`

	// Email is the abuse contact email address.
	// Example: "abuse.de@vodafone.com"
	Email string `json:"email"`

	// Phone is the abuse contact phone number.
	// Example: "+49 6196 52352105"
	Phone string `json:"phone"`
}

NetworkAbuseContactData contains contact details for reporting abuse.

Available when the IP Intelligence module is enabled. Null when the IP Intelligence module is not enabled.

type NetworkAnonymizationData added in v0.3.0 

type NetworkAnonymizationData struct {
	// VPNScore is the likelihood that the IP is from a VPN service.
	VPNScore RiskScore `json:"vpn_score"`

	// ProxyScore is the likelihood that the IP is from a proxy service.
	ProxyScore RiskScore `json:"proxy_score"`

	// Tor indicates whether the IP is a Tor exit node.
	Tor bool `json:"tor"`

	// ICloudPrivateRelay indicates whether the IP is from iCloud Private Relay.
	ICloudPrivateRelay bool `json:"icloud_private_relay"`
}

NetworkAnonymizationData contains detection of VPNs, proxies, and anonymization services.

Available when the Anonymization Detection module is enabled. Null when the Anonymization Detection module is not enabled.

type NetworkAutonomousSystemData added in v0.3.0 

type NetworkAutonomousSystemData struct {
	// Number is the Autonomous System Number (ASN) identifier.
	// Example: 3209 for Vodafone GmbH
	Number int `json:"number"`

	// Name of the autonomous system. This is usually a short name or handle.
	// Example: "VODANET"
	Name string `json:"name"`

	// Company is the organization name that owns the ASN.
	// Example: "Vodafone GmbH"
	Company string `json:"company"`

	// Description of the company that owns the ASN.
	// Example: "Provides mobile and fixed broadband and telecommunication services to consumers and businesses."
	Description string `json:"description"`

	// Domain name associated with the ASN.
	// Example: "vodafone.de"
	Domain string `json:"domain"`

	// Country is the two-letter ISO 3166-1 alpha-2 country code where the ASN is registered.
	// Example: "DE"
	Country string `json:"country"`

	// RIR is the Regional Internet Registry that allocated the ASN.
	// Example: "RIPE"
	RIR string `json:"rir"`

	// Route is the IP route associated with the ASN in CIDR notation.
	// Example: "88.64.0.0/12"
	Route string `json:"route"`

	// Type of the autonomous system.
	// Example: "isp"
	Type string `json:"type"`
}

NetworkAutonomousSystemData contains information about the AS that owns the IP.

Available when the IP Intelligence module is enabled for your account. Null when the IP Intelligence module is not enabled for your account.

type NetworkData added in v0.3.0 

type NetworkData struct {
	// IP is the IP address used when requesting the challenge.
	// Example: "88.64.4.22"
	IP string `json:"ip"`

	// AS contains Autonomous System information.
	//
	// Available when the IP Intelligence module is enabled.
	// Null when the IP Intelligence module is not enabled.
	AS null.Value[NetworkAutonomousSystemData] `json:"as"`

	// Geolocation information.
	//
	// Available when the IP Intelligence module is enabled.
	// Null when the IP Intelligence module is not enabled.
	Geolocation null.Value[NetworkGeolocationData] `json:"geolocation"`

	// AbuseContact is the abuse contact information.
	//
	// Available when the IP Intelligence module is enabled.
	// Null when the IP Intelligence module is not enabled.
	AbuseContact null.Value[NetworkAbuseContactData] `json:"abuse_contact"`

	// Anonymization contains IP masking/anonymization information.
	//
	// Available when the Anonymization Detection module is enabled.
	// Null when the Anonymization Detection module is not enabled.
	Anonymization null.Value[NetworkAnonymizationData] `json:"anonymization"`
}

NetworkData contains information about the network.

type NetworkGeolocationCountryData added in v0.3.0 

type NetworkGeolocationCountryData struct {
	// ISO2 is the two-letter ISO 3166-1 alpha-2 country code.
	// Example: "DE"
	ISO2 string `json:"iso2"`

	// ISO3 is the three-letter ISO 3166-1 alpha-3 country code.
	// Example: "DEU"
	ISO3 string `json:"iso3"`

	// Name is the English name of the country.
	// Example: "Germany"
	Name string `json:"name"`

	// NameNative is the native name of the country.
	// Example: "Deutschland"
	NameNative string `json:"name_native"`

	// Region is the major world region.
	// Example: "Europe"
	Region string `json:"region"`

	// Subregion is the more specific world region.
	// Example: "Western Europe"
	Subregion string `json:"subregion"`

	// Currency is the ISO 4217 currency code.
	// Example: "EUR"
	Currency string `json:"currency"`

	// CurrencyName is the full name of the currency.
	// Example: "Euro"
	CurrencyName string `json:"currency_name"`

	// PhoneCode is the international dialing code.
	// Example: "49"
	PhoneCode string `json:"phone_code"`

	// Capital is the name of the capital city.
	// Example: "Berlin"
	Capital string `json:"capital"`
}

NetworkGeolocationCountryData contains detailed country data.

type NetworkGeolocationData added in v0.3.0 

type NetworkGeolocationData struct {
	// Country information.
	Country NetworkGeolocationCountryData `json:"country"`

	// City name. Empty string if unknown.
	// Example: "Eschborn"
	City string `json:"city"`

	// State, region, or province. Empty string if unknown.
	// Example: "Hessen"
	State string `json:"state"`
}

NetworkGeolocationData contains geographic location of the IP address.

Available when the IP Intelligence module is enabled. Null when the IP Intelligence module is not enabled.

type RiskIntelligenceData added in v0.3.0 

type RiskIntelligenceData struct {
	// RiskScores from various signals, these summarize the risk intelligence assessment.
	//
	// Available when the Risk Scores module is enabled.
	// Null when the Risk Scores module is not enabled.
	RiskScores null.Value[RiskScoresData] `json:"risk_scores"`

	// Network contains network-related risk intelligence.
	Network NetworkData `json:"network"`

	// Client contains client/device risk intelligence.
	Client ClientData `json:"client"`
}

RiskIntelligenceData contains all risk intelligence information.

Field availability depends on enabled modules.

type RiskIntelligenceRetrieveRequest added in v0.4.0 

type RiskIntelligenceRetrieveRequest struct {
	// The token that you want to retrieve risk intelligence for.
	Token string `json:"token"`
	// Optional: the sitekey that you want to make sure the token was generated from.
	Sitekey string `json:"sitekey,omitempty"`
}

RiskIntelligenceRetrieveRequest is the request body for the /api/v2/riskIntelligence/retrieve endpoint.

type RiskIntelligenceRetrieveResponse added in v0.4.0 

type RiskIntelligenceRetrieveResponse struct {
	Success bool `json:"success"`

	// This field is only present when the success field is true.
	Data *RiskIntelligenceRetrieveResponseData `json:"data,omitempty"`
	// This field is only present when the success field is false.
	Error *VerifyResponseError `json:"error,omitempty"`
}

RiskIntelligenceRetrieveResponse is the response body for the /api/v2/riskIntelligence/retrieve endpoint.

type RiskIntelligenceRetrieveResponseData added in v0.4.0 

type RiskIntelligenceRetrieveResponseData struct {
	// EventID is a unique identifier for this risk intelligence retrieve call.
	EventID string `json:"event_id"`

	// Token contains metadata about the token used for retrieval.
	Token RiskIntelligenceTokenData `json:"token"`

	// RiskIntelligenceRaw contains the raw JSON risk information extracted from the provided token.
	//
	// Note this is the raw JSON data, you probably want to use the RiskIntelligence field instead. This field is
	// available in case you need to access fields that are not yet modeled in the SDK.
	RiskIntelligenceRaw null.Value[json.RawMessage] `json:"risk_intelligence"`

	// RiskIntelligence contains risk information extracted from the provided token.
	RiskIntelligence null.Value[RiskIntelligenceData] `json:"-"`
}

RiskIntelligenceRetrieveResponseData is the data field in a successful retrieve response.

func (*RiskIntelligenceRetrieveResponseData) UnmarshalJSON added in v0.4.0 

func (r *RiskIntelligenceRetrieveResponseData) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom JSON unmarshaling for VerifyResponseData. It automatically populates the RiskIntelligence field from RiskIntelligenceRaw.

type RiskIntelligenceRetrieveResult added in v0.4.0 

type RiskIntelligenceRetrieveResult struct {
	// Success is true if the token was valid and data retrieval succeeded.
	Success bool

	// Status is the HTTP response status code of the request to the Friendly Captcha API.
	Status int
	// contains filtered or unexported fields
}

RiskIntelligenceRetrieveResult wraps the response from the Friendly Captcha API retrieve endpoint.

func NewRiskIntelligenceRetrieveResult added in v0.4.0 

func NewRiskIntelligenceRetrieveResult(
	response RiskIntelligenceRetrieveResponse,
	status int,
	err error,
) RiskIntelligenceRetrieveResult

NewRiskIntelligenceRetrieveResult returns a new RiskIntelligenceRetrieveResult. This is generally only useful if you want to create a result manually for testing purposes.

func (RiskIntelligenceRetrieveResult) HTTPStatusCode added in v0.4.0 

func (r RiskIntelligenceRetrieveResult) HTTPStatusCode() int

HTTPStatusCode returns the HTTP status code of the response from the Friendly Captcha API.

func (RiskIntelligenceRetrieveResult) IsErrorDueToClientError added in v0.4.0 

func (r RiskIntelligenceRetrieveResult) IsErrorDueToClientError() bool

IsErrorDueToClientError returns true for non-200 server responses, typically caused by invalid credentials or payload.

func (RiskIntelligenceRetrieveResult) IsRequestError added in v0.4.0 

func (r RiskIntelligenceRetrieveResult) IsRequestError() bool

IsRequestError returns true if an error occurred while sending the request to the Friendly Captcha API or interpreting its response.

func (RiskIntelligenceRetrieveResult) IsValid added in v0.4.0 

func (r RiskIntelligenceRetrieveResult) IsValid() bool

IsValid returns true if the token used for retrieval is valid and the retrieval succeeded.

func (RiskIntelligenceRetrieveResult) RequestError added in v0.4.0 

func (r RiskIntelligenceRetrieveResult) RequestError() error

RequestError returns the error, if any (nil otherwise).

func (RiskIntelligenceRetrieveResult) Response added in v0.4.0 

func (r RiskIntelligenceRetrieveResult) Response() RiskIntelligenceRetrieveResponse

Response returns the response from the Friendly Captcha API.

func (RiskIntelligenceRetrieveResult) WasAbleToRetrieve added in v0.4.0 

func (r RiskIntelligenceRetrieveResult) WasAbleToRetrieve() bool

WasAbleToRetrieve returns true if retrieval succeeded and the server returned HTTP 200.

type RiskIntelligenceTokenData added in v0.4.0 

type RiskIntelligenceTokenData struct {
	// Timestamp when the token was generated.
	Timestamp time.Time `json:"timestamp"`
	// Timestamp when the token expires.
	ExpiresAt time.Time `json:"expires_at"`
	// Number of times the token has been used.
	NumUses int64 `json:"num_uses"`
	// The origin of the site where the token was generated.
	Origin string `json:"origin"`
}

RiskIntelligenceTokenData is metadata about the risk intelligence token in a retrieve response.

type RiskScore added in v0.3.0 

type RiskScore uint8

RiskScore represents a risk score value ranging from 1 to 5.

  • 0: Unknown or missing
  • 1: Very low risk
  • 2: Low risk
  • 3: Medium risk
  • 4: High risk
  • 5: Very high risk
const (
	// RiskScoreUnknown represents an unknown or missing risk score.
	RiskScoreUnknown RiskScore = 0
	// RiskScoreVeryLow represents a very low risk score (1/5).
	RiskScoreVeryLow RiskScore = 1
	// RiskScoreLow represents a low risk score (2/5).
	RiskScoreLow RiskScore = 2
	// RiskScoreMedium represents a medium risk score (3/5).
	RiskScoreMedium RiskScore = 3
	// RiskScoreHigh represents a high risk score (4/5).
	RiskScoreHigh RiskScore = 4
	// RiskScoreVeryHigh represents a very high risk score (5/5).
	RiskScoreVeryHigh RiskScore = 5
)

type RiskScoresData added in v0.3.0 

type RiskScoresData struct {
	// Overall risk score combining all signals.
	Overall RiskScore `json:"overall"`

	// Network-related risk score. Captures likelihood of automation/malicious activity based on
	// IP address, ASN, reputation, geolocation, past abuse from this network, and other network signals.
	Network RiskScore `json:"network"`

	// Browser-related risk score. Captures likelihood of automation, malicious activity or browser spoofing based on
	// user agent consistency, automation traces, past abuse, and browser characteristics.
	Browser RiskScore `json:"browser"`
}

RiskScoresData summarizes the entire risk intelligence assessment into scores per category.

Available when the Risk Scores module is enabled for your account. Null when the Risk Scores module is not enabled for your account.

type TLSSignatureData added in v0.3.0 

type TLSSignatureData struct {
	// JA3 is the JA3 hash.
	// Example: "d87a30a5782a73a83c1544bb06332780"
	JA3 string `json:"ja3"`

	// JA3N is the JA3N hash.
	// Example: "28ecc2d2875b345cecbb632b12d8c1e0"
	JA3N string `json:"ja3n"`

	// JA4 is the JA4 signature.
	// Example: "t13d1516h2_8daaf6152771_02713d6af862"
	JA4 string `json:"ja4"`
}

TLSSignatureData contains TLS client hello signatures.

Available when the Bot Detection module is enabled. Null when the Bot Detection module is not enabled.

type VerifyRequest 

type VerifyRequest struct {
	// The response value that the user submitted in the frc-captcha-response field.
	Response string `json:"response"`
	// Optional: the sitekey that you want to make sure the puzzle was generated from.
	Sitekey string `json:"sitekey,omitempty"`
}

VerifyRequest is the request body for the /api/v2/captcha/siteverify endpoint. As a user of the SDK you generally don't need to create this struct yourself, instead you should use the Client's methods.

type VerifyResponse 

type VerifyResponse struct {
	Success bool `json:"success"`

	// This field is only present when the success field is true.
	Data *VerifyResponseData `json:"data,omitempty"`
	// This field is only present when the success field is false.
	Error *VerifyResponseError `json:"error,omitempty"`
}

VerifyResponse is the response body for the /api/v2/captcha/siteverify endpoint. This is what the Friendly Captcha API returns.

type VerifyResponseChallengeData added in v0.2.0 

type VerifyResponseChallengeData struct {
	Timestamp time.Time `json:"timestamp"`
	Origin    string    `json:"origin"`
}

VerifyResponseChallengeData is the data found in the challenge field of a VerifyResponse. It contains information about the challenge that was solved.

type VerifyResponseData added in v0.2.0 

type VerifyResponseData struct {
	// EventID is a unique identifier for this siteverify call.
	EventID string `json:"event_id"`

	// Challenge contains information about the challenge that was solved.
	Challenge VerifyResponseChallengeData `json:"challenge"`

	// RiskIntelligenceRaw contains risk information about the solver of the captcha.
	// This may be `null` if risk intelligence is not enabled for your Friendly Captcha account.
	//
	// Note this is the raw JSON data, you probably want to use the RiskIntelligence field instead. This field is
	// available in case you need to access fields that are not yet modeled in the SDK.
	RiskIntelligenceRaw null.Value[json.RawMessage] `json:"risk_intelligence"`

	// RiskIntelligence contains risk information about the solver of the captcha.
	// This may be `null` if risk intelligence is not enabled for your Friendly Captcha account.
	RiskIntelligence null.Value[RiskIntelligenceData] `json:"-"`
}

VerifyResponseData is the data found in the data field of a VerifyResponse.

func (*VerifyResponseData) UnmarshalJSON added in v0.3.0 

func (v *VerifyResponseData) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom JSON unmarshaling for VerifyResponseData. It automatically populates the RiskIntelligence field from RiskIntelligenceRaw.

type VerifyResponseError added in v0.2.0 

type VerifyResponseError struct {
	ErrorCode ErrorCode `json:"error_code"`
	Detail    string    `json:"detail"`
}

VerifyResponseError is the data found in the error field of a VerifyResponse in case of an error.

type VerifyResult added in v0.2.0 

type VerifyResult struct {
	// Success is true if the captcha was solved correctly.
	Success bool

	// Status is the HTTP Response status code of the request to the Friendly Captcha API.
	Status int
	// contains filtered or unexported fields
}

VerifyResult wraps the response from the Friendly Captcha API when verifying a captcha, making it easier to work with. In the simplest case, you can just check `ShouldAccept` to see if the captcha was solved correctly or if you should accept it anyway (e.g. because the API was down).

func NewVerifyResult added in v0.2.4 

func NewVerifyResult(response VerifyResponse, status int, strict bool, err error) VerifyResult

NewVerifyResult returns a new VerifyResult with the given response, status code, strict mode and error. This is generally only useful if you want to create a VerifyResult manually for testing purposes.

func (VerifyResult) HTTPStatusCode added in v0.2.0 

func (r VerifyResult) HTTPStatusCode() int

HTTPStatusCode returns the HTTP status code of the response from the Friendly Captcha API.

func (VerifyResult) IsErrorDueToClientError added in v0.2.0 

func (r VerifyResult) IsErrorDueToClientError() bool

This is an error that is not due to a connection error, but due to a client error (e.g. wrong API key). You should log this and notify yourself and fix this as soon as possible.

It's usually still a good idea to accept the captcha: it's better to accept any captcha than to lock all users out.

func (VerifyResult) IsRequestError added in v0.2.0 

func (r VerifyResult) IsRequestError() bool

IsRequestError returns true if an error occurred while sending the request to the Friendly Captcha API or interpreting its response. This could be due to network connectivity issues, or the Friendly Captcha API experiencing downtime.

func (VerifyResult) RequestError added in v0.2.0 

func (r VerifyResult) RequestError() error

RequestError returns the error, if any (nil otherwise).

func (VerifyResult) Response added in v0.2.0 

func (r VerifyResult) Response() VerifyResponse

Response returns the response from the Friendly Captcha API.

func (VerifyResult) ShouldAccept added in v0.2.0 

func (r VerifyResult) ShouldAccept() bool

ShouldAccept returns true if you should allow the request to pass through. It is possible that verification wasn't possible, perhaps the API is unavailable. In that case this function will also return true, unless you enable `strict` mode for the client.

func (VerifyResult) ShouldReject added in v0.2.0 

func (r VerifyResult) ShouldReject() bool

ShouldReject is the inverse of ShouldAccept.

func (VerifyResult) Strict added in v0.2.0 

func (r VerifyResult) Strict() bool

Strict returns whether the verification was strict.

If strict is false (= the default), and verification was not able to happen (e.g. because your API key is incorrect, or the Friendly Captcha API is down) then `ShouldAccept` will return true regardless.

func (VerifyResult) WasAbleToVerify added in v0.2.0 

func (r VerifyResult) WasAbleToVerify() bool

WasAbleToVerify returns true if the captcha could be verified. If this is false, you should log the reason why and investigate (you can retrieve the error using the `RequestError` method). The `IsErrorDueToClientError` method will tell you if the error was due to a client error (e.g. wrong API key) - which will require your action to fix.

Source Files

View all Source files

Directories

Path Synopsis
example module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.