Solve captchas from PHP with one function

<?php
declare(strict_types=1);

const BYPASS_API_URL = 'https://bypass.so';

final class BypassError extends RuntimeException
{
    public function __construct(
        public readonly string $errorCode,
        string $description = '',
        public readonly ?string $taskId = null,
    ) {
        parent::__construct("$errorCode: $description");
    }
}

function bypass_key(): string
{
    return getenv('BYPASS_API_KEY') ?: '';
}

/** Sends one request and returns the decoded JSON. Any errorId != 0 becomes a BypassError. */
function bypass_call(string $method, string $path, ?array $body = null, bool $bearer = false): array
{
    $headers = [];
    if ($body !== null) {
        $headers[] = 'Content-Type: application/json';
    }
    if ($bearer) {
        $headers[] = 'Authorization: Bearer ' . bypass_key();
    }
    $ch = curl_init(BYPASS_API_URL . $path);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_TIMEOUT => 30,
    ]);
    if ($method === 'POST') {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $body === null ? '' : json_encode($body, JSON_THROW_ON_ERROR));
    }
    $raw = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    $error = curl_error($ch);

    if ($raw === false) {
        throw new BypassError('HTTP_ERROR', $error);
    }
    $data = json_decode($raw, true);
    if (!is_array($data)) {
        throw new BypassError('HTTP_ERROR', "HTTP $status without a JSON body");
    }
    if (!empty($data['errorId'])) {
        throw new BypassError($data['errorCode'] ?? 'ERROR_UNKNOWN', $data['errorDescription'] ?? '', $data['taskId'] ?? null);
    }
    return $data;
}

/** Creates a task and polls every $pollEvery seconds until it is ready. Returns the solution plus taskId. */
function bypass_solve(string $type, array $params, int $timeout = 120, int $pollEvery = 2): array
{
    $key = bypass_key();
    if ($key === '') {
        throw new BypassError('ERROR_KEY_INVALID', 'set the BYPASS_API_KEY environment variable');
    }
    $data = bypass_call('POST', '/createTask', ['clientKey' => $key, 'type' => $type] + $params);
    $taskId = $data['taskId'];
    $deadline = time() + $timeout;

    while (($data['status'] ?? '') !== 'ready') {
        if (($data['status'] ?? '') === 'failed') {
            throw new BypassError('ERROR_CAPTCHA_UNSOLVABLE', 'task failed', $taskId);
        }
        if (time() > $deadline) {
            throw new BypassError('CLIENT_TIMEOUT', "task $taskId was not ready after {$timeout}s", $taskId);
        }
        sleep($pollEvery);
        $data = bypass_call('GET', '/getTaskResult/' . rawurlencode($taskId) . '?clientKey=' . rawurlencode($key));
    }
    return ($data['solution'] ?? []) + ['taskId' => $taskId];
}

/** The token for widget types, or the text for recognition types. */
function bypass_answer(array $solution): ?string
{
    return $solution['gRecaptchaResponse'] ?? $solution['token'] ?? $solution['text'] ?? null;
}

function bypass_balance(): array
{
    return bypass_call('GET', '/balance', null, true);
}

function bypass_report_bad(string $taskId): array
{
    return bypass_call('POST', '/reportBad?task_id=' . rawurlencode($taskId), null, true);
}

<?php
declare(strict_types=1);

use GuzzleHttp\Client;
use GuzzleHttp\Exception\GuzzleException;

final class BypassError extends RuntimeException
{
    public function __construct(
        public readonly string $errorCode,
        string $description = '',
        public readonly ?string $taskId = null,
    ) {
        parent::__construct("$errorCode: $description");
    }
}

final class Bypass
{
    private Client $http;
    private string $key;

    public function __construct(?string $key = null)
    {
        $this->key = $key ?? (getenv('BYPASS_API_KEY') ?: '');
        $this->http = new Client([
            'base_uri' => 'https://bypass.so',
            'timeout' => 30,
            'connect_timeout' => 10,
            'http_errors' => false, // error replies carry JSON we want to read
        ]);
    }

    public function solve(string $type, array $params, int $timeout = 120, int $pollEvery = 2): array
    {
        if ($this->key === '') {
            throw new BypassError('ERROR_KEY_INVALID', 'set the BYPASS_API_KEY environment variable');
        }
        $data = $this->call('POST', '/createTask', [
            'json' => ['clientKey' => $this->key, 'type' => $type] + $params,
        ]);
        $taskId = $data['taskId'];
        $deadline = time() + $timeout;

        while (($data['status'] ?? '') !== 'ready') {
            if (($data['status'] ?? '') === 'failed') {
                throw new BypassError('ERROR_CAPTCHA_UNSOLVABLE', 'task failed', $taskId);
            }
            if (time() > $deadline) {
                throw new BypassError('CLIENT_TIMEOUT', "task $taskId was not ready after {$timeout}s", $taskId);
            }
            sleep($pollEvery);
            $data = $this->call('GET', '/getTaskResult/' . rawurlencode($taskId), [
                'query' => ['clientKey' => $this->key],
            ]);
        }
        return ($data['solution'] ?? []) + ['taskId' => $taskId];
    }

    public function balance(): array
    {
        return $this->call('GET', '/balance', ['headers' => $this->bearer()]);
    }

    public function reportBad(string $taskId): array
    {
        return $this->call('POST', '/reportBad', ['query' => ['task_id' => $taskId], 'headers' => $this->bearer()]);
    }

    private function bearer(): array
    {
        return ['Authorization' => 'Bearer ' . $this->key];
    }

    private function call(string $method, string $uri, array $options): array
    {
        try {
            $res = $this->http->request($method, $uri, $options);
        } catch (GuzzleException $e) {
            throw new BypassError('HTTP_ERROR', $e->getMessage());
        }
        $data = json_decode((string) $res->getBody(), true);
        if (!is_array($data)) {
            throw new BypassError('HTTP_ERROR', 'HTTP ' . $res->getStatusCode() . ' without a JSON body');
        }
        if (!empty($data['errorId'])) {
            throw new BypassError($data['errorCode'] ?? 'ERROR_UNKNOWN', $data['errorDescription'] ?? '', $data['taskId'] ?? null);
        }
        return $data;
    }
}