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

SDK Java resmi untuk API penyelesaian CAPTCHA [CaptchaSonic](https://captchasonic.com).

## Transport

Menggunakan gRPC native melalui `grpc-netty-shaded`. Gambar dikirim sebagai biner mentah — tanpa overhead base64.

## Instalasi

### Gradle

```groovy
implementation 'com.captchasonic:captchasonic:1.0.0'
```

### Maven

```xml
<dependency>
    <groupId>com.captchasonic</groupId>
    <artifactId>captchasonic</artifactId>
    <version>1.0.0</version>
</dependency>
```

## Mulai Cepat

```java
import com.captchasonic.CaptchaSonicClient;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;

try (var client = new CaptchaSonicClient("sonic_your_api_key")) {
    double balance = client.getBalance();
    System.out.println("Balance: $" + balance);

    byte[] tile = Files.readAllBytes(Path.of("tile.png"));
    var result = client.solvePopularCaptcha(
        List.of(tile), "Select all traffic lights", "objectClassify"
    );
    System.out.println(result.getTypedSolution().getGrid().getObjectsList());
}
```

### Pola Builder

```java
CaptchaSonicClient client = CaptchaSonicClient.builder()
    .apiKey("sonic_xxx")
    .host("api.captchasonic.com")
    .port(443)
    .timeout(Duration.ofSeconds(120))
    .build();
```

### Endpoint Kustom

```java
var client = new CaptchaSonicClient("sonic_xxx", "api.captchasonic.com", 443, true);
```

Client bersifat **thread-safe** — buat satu instance dan gunakan ulang.

---

## Solver Gambar

### `solvePopularCaptcha()`

```java
client.solvePopularCaptcha(images, question, questionType);

// Full options
client.solvePopularCaptcha(
    images,                          // List<byte[]>
    "Select all traffic lights",     // question
    "objectClassify",                // questionType
    exampleImages,                   // List<byte[]>, nullable
    false,                           // screenshot
    "https://example.com",           // websiteUrl, nullable
    "sitekey123"                     // websiteKey, nullable
);
```

### `solveRecaptchaV2()`

```java
client.solveRecaptchaV2(images, "traffic lights");

// With questionType + options
client.solveRecaptchaV2(
    images,                   // List<byte[]>
    "traffic lights",         // question
    "split_33",               // questionType: "split_33" | "33" | "44"
    "https://example.com",    // websiteUrl, nullable
    null                      // websiteKey, nullable
);
```

### `solveGeetest()`

```java
client.solveGeetest("geetest_nine:Select the bear", images);

// Full options
client.solveGeetest(question, images, examples, bgImage, gtv, websiteUrl);
```

### `solveOcr()`

```java
client.solveOcr(images);

// With options
client.solveOcr(images, "mtcaptcha", false, false, 3, 4, "https://example.com");
```

### `solveTikTok()`

```java
// Type-based routing (alias expansion built-in)
client.solveTikTok("whirl", "Rotate to match", images);
client.solveTikTok("click", "Select the shape", images, examples, websiteUrl);
// Accepted types: "click", "whirl", "slide", "tiktok_click", etc.
```

### `solveBinance()`

```java
client.solveBinance("grid", "Select the bicycle", images);
client.solveBinance("slide", "", images, examples, websiteUrl);
// Accepted types: "grid", "slide", "binance_grid", "binance_slide"
```

### `solveAwsWaf()`

```java
client.solveAwsWaf(images, "grid:vehicles:cars");
client.solveAwsWaf(images, question, websiteUrl, websiteKey);
```

### `solveSlideImage()`

```java
client.solveSlideImage(List.of(background, piece));
// Returns: result.getTypedSolution().getSlide().getX()
```

---

## Metode Otomasi Token

Metode ini mengirim task lalu melakukan polling hingga token dikembalikan (maksimal 120 detik).

```java
client.solveTurnstile(websiteUrl, websiteKey);
client.solveTurnstile(websiteUrl, websiteKey, proxy);
client.solvePopularCaptchaToken(websiteUrl, websiteKey, proxy);
client.solveRecaptchaV2Token(websiteUrl, websiteKey, proxy);
client.solveRecaptchaV3Token(websiteUrl, websiteKey, proxy);
client.solveCloudflare(websiteUrl, websiteKey, proxy);  // proxy required
```

Setiap metode blocking memiliki varian `Async` yang mengembalikan `CompletableFuture<CreateTaskResponse>`.

---

## Metode Utilitas

```java
double balance = client.getBalance();
HealthCheckResponse health = client.healthCheck();
GetTaskResultResponse result = client.getTaskResult(taskId);
```

---

## Penanganan Error

```java
import com.captchasonic.*;

try {
    client.solvePopularCaptcha(images, question, questionType);
} catch (InvalidApiKeyException e)       { /* errorId=1 */ }
  catch (InsufficientBalanceException e) { /* errorId=2 */ }
  catch (DailyLimitExceededException e)  { /* errorId=3 */ }
  catch (MinuteLimitExceededException e) { /* errorId=4 */ }
  catch (QuotaExceededException e)       { /* errorId=5 */ }
  catch (PlanExpiredException e)         { /* errorId=6 */ }
  catch (CaptchaSonicException e)        { /* other errors */ }
```

Mencoba ulang pada `UNAVAILABLE`, `RESOURCE_EXHAUSTED`, `DEADLINE_EXCEEDED` dengan exponential backoff.

---
