azcaptcha

package module
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 13 Imported by: 0

README

AZcaptcha Go SDK

Official Go client for AZcaptcha — image captchas, reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile, FunCaptcha and GeeTest.

  • Idiomatic Go: context.Context on every call, typed errors with errors.Is sentinels, Config overrides, no required options.
  • 2Captcha-compatible surface (Solve, Result, Balance, ReportBad) plus the modern JSON API (CreateTask, GetTaskResult).
  • Typed errors for every API code (spec-v1.0.0).
  • Contract polling with NO_SLOT backoff and per-type deadlines.
  • Zero dependencies beyond the standard library.

Install

go get github.com/azcaptcha/azcaptcha-go

Quickstart

package main

import (
	"context"
	"fmt"

	azcaptcha "github.com/azcaptcha/azcaptcha-go"
)

func main() {
	client, err := azcaptcha.New("YOUR_API_KEY", azcaptcha.Config{})
	if err != nil {
		panic(err)
	}
	ctx := context.Background()

	token, err := client.SolveRecaptchaV2(ctx,
		"6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
		"https://example.com/login", nil)
	if err != nil {
		panic(err)
	}
	fmt.Println(token)

	answer, err := client.SolveImageFile(ctx, "captcha.png", nil)
	fmt.Println(answer, err)
}
Low-level (2Captcha style)
taskID, err := client.Submit(ctx, "userrecaptcha", map[string]any{
	"googlekey": "SITEKEY",
	"pageurl":   "https://example.com/",
})
token, err := client.WaitResult(ctx, taskID, 300*time.Second)
Modern JSON API
taskID, err := client.CreateTask(ctx, "RecaptchaV2TaskProxyless", map[string]any{
	"websiteURL": "https://example.com/login",
	"websiteKey": "SITEKEY",
})
solution, err := client.WaitTaskResult(ctx, taskID, 300*time.Second)
fmt.Println(solution["gRecaptchaResponse"])

Proxies

_, err = client.Submit(ctx, "turnstile", map[string]any{
	"sitekey":  sitekey,
	"pageurl":  pageurl,
	"proxy":    "socks5://user:pass@1.2.3.4:1080",
})

Any accepted spelling works (scheme://user:pass@host:port, host:port:user:pass, user:pass@host:port). The scheme is never sent upstream; proxytype is derived (http/https → HTTP, socks4, socks5).

Errors

*azcaptcha.Error carries Code and Retryable; category sentinels support errors.Is:

import "errors"

token, err := client.SolveTurnstile(ctx, sitekey, pageurl, nil)
switch {
case errors.Is(err, azcaptcha.ErrBalance):
	// ERROR_ZERO_BALANCE
case errors.Is(err, azcaptcha.ErrCapacity):
	// ERROR_NO_SLOT_AVAILABLE — retry with backoff
case errors.Is(err, azcaptcha.ErrResult):
	// unsolvable / timeout / expired
}

WaitResult retries only codes marked retryable and backs off 10s ×1.5 up to 60s. Context cancellation aborts polling immediately.

Timeouts

Defaults match server settings: image 120s, hCaptcha 120s, Turnstile 180s, reCAPTCHA and others 300s. Override with SolveWithTimeout(ctx, method, params, 90*time.Second).

Custom transport

client, err := azcaptcha.New("KEY", azcaptcha.Config{
	Transport: myTransport, // implements azcaptcha.Transport
	Sleep:     mySleep,     // func(time.Duration)
})

License

MIT — see LICENSE.

Documentation

Index

Constants

View Source
const (
	// NotReady is part of the wire contract — spelling included.
	NotReady = "CAPCHA_NOT_READY"
	// SoftID is sent for upstream attribution once assigned; zero omits it.
	SoftID = 0
)

Variables

View Source
var (
	ErrProcessing = errors.New("azcaptcha: processing")
	ErrAuth       = errors.New("azcaptcha: auth")
	ErrBalance    = errors.New("azcaptcha: balance")
	ErrRequest    = errors.New("azcaptcha: request")
	ErrLimit      = errors.New("azcaptcha: limit")
	ErrCapacity   = errors.New("azcaptcha: capacity")
	ErrService    = errors.New("azcaptcha: service")
	ErrResult     = errors.New("azcaptcha: result")
	ErrProxy      = errors.New("azcaptcha: proxy")
	ErrPingback   = errors.New("azcaptcha: pingback")
	ErrModule     = errors.New("azcaptcha: module")
	ErrNetwork    = errors.New("azcaptcha: network")
	ErrUnknown    = errors.New("azcaptcha: unknown")
)

Category sentinels — use with errors.Is to branch without matching codes.

View Source
var DefaultTimeouts = map[string]time.Duration{
	"base64":              120 * time.Second,
	"grid":                120 * time.Second,
	"userrecaptcha":       300 * time.Second,
	"recaptcha_v3":        300 * time.Second,
	"hcaptcha":            120 * time.Second,
	"hcaptcha_enterprise": 120 * time.Second,
	"turnstile":           180 * time.Second,
	"funcaptcha":          300 * time.Second,
	"geetest":             300 * time.Second,
	"geetest_v4":          300 * time.Second,
	"mtcaptcha":           300 * time.Second,
	"friendlycaptcha":     300 * time.Second,
	"altcha":              300 * time.Second,
	"cf_clearance":        300 * time.Second,
	"aws_waf":             300 * time.Second,
	"filecrypt":           300 * time.Second,
}

DefaultTimeouts mirror the server-side expiry per method.

Functions

func ImageBase64

func ImageBase64(image string) string

ImageBase64 normalises a data: URI or base64 string to bare base64.

func ImageBody

func ImageBody(image []byte) string

ImageBody encodes raw bytes as bare base64.

func ImageFile

func ImageFile(path string) (string, error)

ImageFile reads a captcha image from disk and encodes it.

func NormalizeProxy

func NormalizeProxy(proxy string) (string, string, error)

NormalizeProxy accepts scheme://user:pass@host:port, host:port:user:pass and user:pass@host:port. The scheme is never sent in the proxy field.

func Taxonomy

func Taxonomy() map[string]bool

Taxonomy exposes code -> retryable for tests and callers.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client talks to the AZcaptcha API. It is safe for concurrent use.

func New

func New(apiKey string, cfg Config) (*Client, error)

New validates the key and wires defaults.

func (*Client) Balance

func (c *Client) Balance(ctx context.Context) (float64, error)

Balance returns the account balance in USD.

func (*Client) CreateTask

func (c *Client) CreateTask(ctx context.Context, taskType string, task map[string]any) (int, error)

CreateTask submits a modern-API task and returns its numeric id.

func (*Client) GetTaskResult

func (c *Client) GetTaskResult(ctx context.Context, taskID int) (map[string]any, error)

GetTaskResult polls the modern API once.

func (*Client) ReportBad

func (c *Client) ReportBad(ctx context.Context, taskID string) (bool, error)

ReportBad flags a solution as incorrect.

func (*Client) Result

func (c *Client) Result(ctx context.Context, taskID string) (string, error)

Result fetches a solution once; ErrProcessing means poll again.

func (*Client) Solve

func (c *Client) Solve(ctx context.Context, method string, params map[string]any) (string, error)

Solve submits and waits, using the per-method timeout from DefaultTimeouts.

func (*Client) SolveFunCaptcha

func (c *Client) SolveFunCaptcha(ctx context.Context, publickey, pageurl string, params map[string]any) (string, error)

func (*Client) SolveGeeTest

func (c *Client) SolveGeeTest(ctx context.Context, gt, challenge, pageurl string, params map[string]any) (string, error)

func (*Client) SolveHCaptcha

func (c *Client) SolveHCaptcha(ctx context.Context, sitekey, pageurl string, params map[string]any) (string, error)

func (*Client) SolveImage

func (c *Client) SolveImage(ctx context.Context, image []byte, params map[string]any) (string, error)

SolveImage solves a raw image (PNG/JPEG bytes).

func (*Client) SolveImageBase64

func (c *Client) SolveImageBase64(ctx context.Context, image string, params map[string]any) (string, error)

SolveImageBase64 solves an already-encoded image (data: URI accepted).

func (*Client) SolveImageFile

func (c *Client) SolveImageFile(ctx context.Context, path string, params map[string]any) (string, error)

SolveImageFile reads a file and solves it.

func (*Client) SolveRecaptchaV2

func (c *Client) SolveRecaptchaV2(ctx context.Context, sitekey, pageurl string, opts *RecaptchaV2Options) (string, error)

func (*Client) SolveRecaptchaV3

func (c *Client) SolveRecaptchaV3(ctx context.Context, sitekey, pageurl, action string, opts *RecaptchaV3Options) (string, error)

func (*Client) SolveTurnstile

func (c *Client) SolveTurnstile(ctx context.Context, sitekey, pageurl string, params map[string]any) (string, error)

func (*Client) SolveWithTimeout

func (c *Client) SolveWithTimeout(ctx context.Context, method string, params map[string]any, timeout time.Duration) (string, error)

SolveWithTimeout is Solve with an explicit deadline.

func (*Client) Submit

func (c *Client) Submit(ctx context.Context, method string, params map[string]any) (string, error)

Submit creates a legacy task and returns its id.

func (*Client) WaitResult

func (c *Client) WaitResult(ctx context.Context, taskID string, timeout time.Duration) (string, error)

WaitResult polls with the contract delays until ready or timeout.

func (*Client) WaitTaskResult

func (c *Client) WaitTaskResult(ctx context.Context, taskID int, timeout time.Duration) (map[string]any, error)

WaitTaskResult polls until the task is ready or the timeout passes.

type Config

type Config struct {
	Host        string
	HTTPTimeout time.Duration
	SoftID      int
	Transport   Transport
	Sleep       func(time.Duration)
}

Config overrides defaults; the zero value is production-ready.

type Error

type Error struct {
	Code      string
	Retryable bool
	Message   string
	Err       error
}

Error carries the API code and the taxonomy retryable flag.

func ErrFor

func ErrFor(code string) *Error

ErrFor builds the typed error for an API code.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type HTTPTransport

type HTTPTransport struct {
	BaseURL string
	HTTP    *http.Client
}

HTTPTransport is the default transport.

func NewHTTPTransport

func NewHTTPTransport(baseURL string, timeout time.Duration) *HTTPTransport

func (*HTTPTransport) Get

func (t *HTTPTransport) Get(ctx context.Context, path string, query url.Values) (map[string]any, error)

func (*HTTPTransport) PostForm

func (t *HTTPTransport) PostForm(ctx context.Context, path string, form url.Values) (map[string]any, error)

func (*HTTPTransport) PostJSON

func (t *HTTPTransport) PostJSON(ctx context.Context, path string, payload any) (map[string]any, error)

type RecaptchaV2Options

type RecaptchaV2Options struct {
	Invisible  bool
	Enterprise bool
	Params     map[string]any
}

RecaptchaV2Options tunes the v2 helper.

type RecaptchaV3Options

type RecaptchaV3Options struct {
	MinScore float64
	Params   map[string]any
}

RecaptchaV3Options tunes the v3 helper.

type Transport

type Transport interface {
	PostForm(ctx context.Context, path string, form url.Values) (map[string]any, error)
	PostJSON(ctx context.Context, path string, payload any) (map[string]any, error)
	Get(ctx context.Context, path string, query url.Values) (map[string]any, error)
}

Transport is the minimal HTTP surface the client needs; tests provide a fake.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL