Use the ky transport for hCaptcha tasks

Integrate KyClient while retaining SDK-controlled response handling, deadlines, and the distinction between creation and lookup retries.

Let the superclass own the public API

The easycaptcha JavaScript SDK offers KyClient for applications that already use ky. Install the SDK and ky, and import KyClient from @easycaptcha-to/sdk/ky. The backend implements fetching; the superclass defines the public operations and interprets API responses.

That separation matters when you customize a transport. You can inject a ky instance without creating another task lifecycle, another result model, or another balance parser in your application.

Start with a non-mutating operation

import { KyClient } from "@easycaptcha-to/sdk/ky";

const client = new KyClient({
  apiKey: process.env.EASYCAPTCHA_API_KEY,
});
const balance = await client.getBalance();
const exactCredit = BigInt(balance.balance_microcents);
console.log(exactCredit.toString());

Balance arrives as an integer string. BigInt preserves it for exact arithmetic, but it is not directly JSON-serializable. Convert it to a string at your own persistence or response boundary rather than converting every amount to a floating-point number.

The backend disables ky’s automatic retry and timeout behavior for the SDK call path, leaving the shared client in control of deadlines and response interpretation. Review supplied hooks or instances so they do not reintroduce application-level retries for ambiguous task creation.

Add task polling without changing the submission count

Creation and retrieval are different operations. Submit a job once, save task_id, and call getJob for that ID while status is queued or running. End local waiting at an application deadline, but keep enough information to reconcile later.

A task failure in a valid response must reach the lifecycle code. An HTTP failure should reach SDK error handling. A transport failure before creation returns an ID should remain an unknown outcome rather than being converted into a fresh job automatically.

Before a live deployment, test a supplied ky instance with hooks enabled, including shutdown and abort behavior. Compare SDK versus raw HTTP if you are deciding whether an existing networking wrapper should call the API directly or sit behind a supported transport.