{/* GENERATED FROM Captcha-Sonic/captchasonic-go README.md — DO NOT EDIT. Run: bun run migrate:sdk-docs */}

SDK Go chính thức cho API giải CAPTCHA [CaptchaSonic](https://captchasonic.com) — truyền tải nhị phân gRPC (nhanh nhất) + HTTP/REST dự phòng.

## Cài đặt

```bash
go get github.com/Captcha-Sonic/captchasonic-go@latest
```

Hoặc ghim vào một phiên bản cụ thể:

```bash
go get github.com/Captcha-Sonic/captchasonic-go@v1.0.0
```

## Bắt đầu nhanh

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/Captcha-Sonic/captchasonic-go"
)

func main() {
    // Create client — gRPC binary transport (default, fastest)
    client, err := captchasonic.NewClient("sonic_your_api_key")
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    ctx := context.Background()

    // Check balance
    balance, _ := client.GetBalance(ctx)
    fmt.Printf("Balance: $%.4f\n", balance)

    // Solve CAPTCHA — images sent as raw binary (zero base64 overhead)
    imgBytes, _ := os.ReadFile("tile.png")
    resp, err := client.SolvePopularCaptcha(ctx, [][]byte{imgBytes},
        "Select all traffic lights", "objectClassify")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Solution:", resp.TypedSolution.GetGrid().GetObjects())
}
```

## Các phương thức truyền tải

| Phương thức truyền tải | Mặc định | Tốc độ | Ảnh |
|-----------|---------|-------|--------|
| **gRPC** | ✅ có | Nhanh nhất — nhị phân, HTTP/2 | Raw `[]byte` |
| **HTTP** | không | Tốt — JSON REST | Tự động mã hóa base64 |

> **gRPC là mặc định.** Chỉ truyền `WithHTTP()` khi bạn thực sự cần truyền tải REST.

## Tùy chọn cấu hình

```go
// Production gRPC (default)
client, _ := captchasonic.NewClient("sonic_xxxx")

// HTTP/REST transport
client, _ := captchasonic.NewClient("sonic_xxxx", captchasonic.WithHTTP())

// Custom endpoint
client, _ := captchasonic.NewClient("sonic_xxxx",
    captchasonic.WithEndpoint("api.captchasonic.com:443"))

// Local development (insecure gRPC)
client, _ := captchasonic.NewClient("sonic_xxxx",
    captchasonic.WithEndpoint("localhost:50052"),
    captchasonic.WithInsecure())

// Advanced options
captchasonic.WithTimeout(45 * time.Second)
captchasonic.WithGRPCMsgSize(100 * 1024 * 1024) // 100 MB max message
captchasonic.WithHTTPPool(200, 200, 90*time.Second)
```

## Các phương thức giải

### PopularCaptcha 

```go
resp, err := client.SolvePopularCaptcha(ctx, images,
    "Select all traffic lights", "objectClassify",
    captchasonic.WithWebsite("https://example.com", "sitekey"))
```

### ReCaptcha V2

```go
resp, err := client.SolveRecaptchaV2(ctx, images, "traffic lights",
    captchasonic.WithQuestionType("split_33"),
    captchasonic.WithWebsiteURL("https://example.com"))
```

### OCR (Ảnh sang văn bản)

```go
// MtCaptcha
resp, err := client.SolveOcr(ctx, images,
    captchasonic.WithModule("mtcaptcha"),
    captchasonic.WithLengthRange(4, 6))

// BLS (numeric)
resp, err := client.SolveOcr(ctx, images,
    captchasonic.WithModule("bls"),
    captchasonic.WithNumeric())
```

### Geetest

```go
// Nine-grid
resp, err := client.SolveGeetest(ctx, "nine", "the bear",
    captchasonic.WithImages(tiles))

// Slide
resp, err := client.SolveGeetest(ctx, "slide", "",
    captchasonic.WithImages(puzzle),
    captchasonic.WithExamples(piece))

// Click
resp, err := client.SolveGeetest(ctx, "click", "the bear",
    captchasonic.WithImages(tiles))
```

### TikTok (theo loại)

```go
resp, err := client.SolveTikTok(ctx, "whirl", "Rotate to match", images,
    captchasonic.WithExamples(examples))

resp, err := client.SolveTikTok(ctx, "click", "Select shape", images)
resp, err := client.SolveTikTok(ctx, "slide", "", images)
```

### Binance (theo loại)

```go
resp, err := client.SolveBinance(ctx, "grid", "Select the bicycle", images)
resp, err := client.SolveBinance(ctx, "slide", "", images)
```

### AWS WAF

```go
resp, err := client.SolveAwsWaf(ctx, images, "Select all squares",
    captchasonic.WithWebsiteURL("https://example.com"))
```

### Turnstile (tác vụ token — tự động thăm dò)

```go
resp, err := client.SolveTurnstile(ctx, "https://example.com", "0x4AAAAAAA")
```

### Các tác vụ token khác

```go
// Cloudflare (proxy REQUIRED)
client.SolveCloudflare(ctx, url, key, "http://user:pass@host:1080")

// reCAPTCHA v2/v3 token
client.SolveRecaptchaV2Token(ctx, url, key, captchasonic.WithProxyless())
client.SolveRecaptchaV3Token(ctx, url, key, captchasonic.WithProxy("..."))

// PopularCaptcha token (PopularCaptcha browser automation)
client.SolvePopularCaptchaToken(ctx, url, key, captchasonic.WithProxyless())
```

## Các hàm trợ giúp tùy chọn tác vụ

```go
captchasonic.WithImages(imgs)              // set images via option
captchasonic.WithExamples(exampleImages)   // reference images
captchasonic.WithScreenshot()              // enable screenshot
captchasonic.WithWebsite(url, key)         // billing: websiteUrl + websiteKey
captchasonic.WithWebsiteURL(url)           // billing: websiteUrl only
captchasonic.WithQuestionType(qt)          // e.g. "objectDrag", "split_33"
captchasonic.WithProxy("http://...")       // proxy for token tasks
captchasonic.WithProxyless()               // proxyless variant
captchasonic.WithModule("bls")             // OCR module
captchasonic.WithNumeric()                 // OCR: digits only
captchasonic.WithCaseSensitive()           // OCR: case sensitive
captchasonic.WithLengthRange(3, 8)         // OCR: min/max text length
captchasonic.WithGeetestVersion(4)         // Geetest version
```

## Xử lý lỗi

```go
resp, err := client.GetBalance(ctx)
if err != nil {
    if sonicErr, ok := err.(*captchasonic.SonicError); ok {
        fmt.Printf("API error %d: %s\n", sonicErr.ErrorID, sonicErr.Message)
    }
}
```

SDK tự động thử lại khi gặp `UNAVAILABLE`, `RESOURCE_EXHAUSTED`, `DEADLINE_EXCEEDED`, với thời gian chờ tăng dần theo cấp số nhân (1 giây, 2 giây).

## Kiểm tra hợp lệ

`NewClient` kiểm tra định dạng API key ngay lập tức — không phát sinh lệnh gọi mạng nào:

- Phải bắt đầu bằng `"sonic_"`
- Tối thiểu 12 ký tự

Kiểm tra theo từng tác vụ: ảnh bắt buộc/số lượng/kích thước, câu hỏi bắt buộc, định dạng proxy.

## Quản lý kết nối (pooling)

- **gRPC**: Một `grpc.ClientConn` duy nhất ghép kênh mọi lệnh gọi thành các stream HTTP/2. Gửi ping keep-alive mỗi 10 giây. Tạo một lần, tái sử dụng qua các goroutine.
- **HTTP**: `http.Transport` với `MaxConnsPerHost` có thể cấu hình (mặc định 100).
