Type hCaptcha job requests and results in TypeScript

Use discriminated job request types to separate recognition, token, and enterprise tasks, then narrow terminal results before reading them.

Select a request type instead of a bag of optional fields

The easycaptcha SDK exports a JobRequest union. Each task kind has its own required fields: recognition carries a challenge object, a regular token task carries sitekey and URL, and an enterprise task also carries enterprise data. This catches many accidental omissions before an HTTP request is made.

A catch-all interface with optional task, sitekey, and rqdata fields would permit combinations the server cannot accept. Use a discriminated request when the operation is known, and narrow the union when a function handles several operations.

Build a checked request

import { FetchClient } from "@easycaptcha-to/sdk/fetch";
import type { JobRequest } from "@easycaptcha-to/sdk";

const request = {
  type: "hcaptcha_token",
  sitekey: "YOUR_SITEKEY",
  url: "https://your-site.example/login",
  hold: 30,
} satisfies JobRequest;

const client = new FetchClient({ apiKey: "YOUR_API_KEY" });
const job = await client.createJob(request);
if (job.status === "completed" && job.type !== "hcaptcha_recognition") {
  const token: string = job.result.token;
  // Forward token to the integration that requested it.
} else if (job.status === "failed") {
  console.error(job.error.detail);
}

The placeholder credential belongs in protected server configuration in a real application. The example intentionally leaves pending jobs visible; your application must retain the ID and schedule further lookups rather than falling through as though the job completed.

Narrow status before result shape

First decide whether a job is terminal. Then select the result type using the task discriminator. A recognition result is not a token result, even when both jobs completed successfully. Avoid casting a result to a token type merely to silence a compiler error.

Static types do not validate arbitrary input from your own user-facing endpoint. Validate untrusted request fields at that boundary and let the API enforce its contract too. Types also do not establish that a returned token was accepted by the eventual application.

Keep a fixture for each task type and each terminal state when changing integrations. Read the binary recognition guide for keyed recognition answers and the enterprise guide for the additional access and input requirements.