@apifuse/provider-sdk 2.2.0-beta.31 → 2.2.0-beta.32

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.32
+
+- Release candidate for main commit 82f1c0c1de916a40c8c74b1d6470a493b134c0ed.
+
 ## 2.2.0-beta.31
 
 - Release candidate for main commit 94006be0852918867d254dc23d0fa8420a07be9c.

package/dist/runtime/resolver-vendors/capsolver.d.ts

@@ -0,0 +1,24 @@
+import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
+import type { TraceRecorder } from "../trace.js";
+import { type ResolverIdentity, type ResolverVendorAdapter } from "./types.js";
+type Delay = (ms: number, signal: AbortSignal) => Promise<void>;
+export interface CapsolverResolverVendorOptions {
+    readonly apiKey?: string;
+    readonly timeoutMs?: number;
+    readonly pollIntervalMs?: number;
+    readonly allowedHosts: readonly string[];
+    readonly fetchImpl?: typeof fetch;
+    readonly baseUrl?: string;
+    /** Test-only clock override; supplying it disables the real-time deadline timer. */
+    readonly now?: () => number;
+    /** Test-only delay override used with `now` to exercise polling without sleeping. */
+    readonly delay?: Delay;
+}
+export interface CapsolverResolverVendorAdapter extends ResolverVendorAdapter {
+    readonly id: "capsolver";
+    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder): Promise<Extract<ChallengeSolution, {
+        readonly form: "token";
+    }>>;
+}
+export declare function createCapsolverResolverVendorAdapter(options: CapsolverResolverVendorOptions): CapsolverResolverVendorAdapter;
+export {};

package/dist/runtime/resolver-vendors/capsolver.js

@@ -0,0 +1,402 @@
+import { redactSensitiveText } from "../request-options.js";
+import { assertResolverHostAllowed } from "./hosts.js";
+import { ResolverChallengeVerdictError, ResolverVendorUnavailableError, resolverVendorSupports, } from "./types.js";
+const CAPSOLVER_VENDOR_ID = "capsolver";
+const DEFAULT_CAPSOLVER_BASE_URL = "https://api.capsolver.com";
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_TIMEOUT_MS = 120_000;
+class CapsolverSolveTimeoutError extends Error {
+    constructor() {
+        super("Capsolver resolver solve budget elapsed");
+        this.name = "CapsolverSolveTimeoutError";
+    }
+}
+class CapsolverUnavailableError extends ResolverVendorUnavailableError {
+    errorCode;
+    errorDescription;
+    responseStatus;
+    responseContentType;
+    responseLength;
+    constructor(reason, options) {
+        super(CAPSOLVER_VENDOR_ID, reason, options);
+        this.errorCode = options.errorCode;
+        this.errorDescription = options.errorDescription;
+        this.responseStatus = options.responseStatus;
+        this.responseContentType = options.responseContentType;
+        this.responseLength = options.responseLength;
+    }
+}
+class CapsolverVerdictError extends ResolverChallengeVerdictError {
+    phase;
+    errorCode;
+    errorDescription;
+    constructor(options) {
+        super(CAPSOLVER_VENDOR_ID, "solve_failed", options);
+        this.phase = options.phase;
+        this.errorCode = options.errorCode;
+        this.errorDescription = options.errorDescription;
+    }
+}
+function isJsonRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function abortReason(signal) {
+    return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+function containsSensitiveValue(value, sensitiveValues) {
+    const secrets = sensitiveValues.filter((secret) => secret.length > 0);
+    if (secrets.length === 0)
+        return false;
+    const seen = new Set();
+    const inspect = (candidate) => {
+        if (typeof candidate === "string") {
+            return secrets.some((secret) => candidate.includes(secret));
+        }
+        if (candidate === null || (typeof candidate !== "object" && typeof candidate !== "function")) {
+            return false;
+        }
+        if (seen.has(candidate))
+            return false;
+        seen.add(candidate);
+        try {
+            for (const property of Reflect.ownKeys(candidate)) {
+                if (typeof property === "string" && inspect(property))
+                    return true;
+                const descriptor = Object.getOwnPropertyDescriptor(candidate, property);
+                if (!descriptor)
+                    return true;
+                if ("value" in descriptor && inspect(descriptor.value))
+                    return true;
+                if (descriptor.get !== undefined || descriptor.set !== undefined)
+                    return true;
+            }
+        }
+        catch {
+            return true;
+        }
+        return false;
+    };
+    return inspect(value);
+}
+function safeCauseOptions(error, sensitiveValues) {
+    return containsSensitiveValue(error, sensitiveValues) ? {} : { cause: error };
+}
+function sanitizedJsonParseCause() {
+    return new SyntaxError("Upstream response failed");
+}
+function raceWithAbort(operation, signal, phase, sensitiveValues = []) {
+    if (signal.aborted)
+        return Promise.reject(abortReason(signal));
+    return new Promise((resolve, reject) => {
+        const cleanup = () => signal.removeEventListener("abort", onAbort);
+        const onAbort = () => {
+            cleanup();
+            reject(abortReason(signal));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        operation().then((value) => {
+            cleanup();
+            resolve(value);
+        }, (error) => {
+            cleanup();
+            if (phase === undefined) {
+                reject(error);
+                return;
+            }
+            reject(new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+                ...safeCauseOptions(error, sensitiveValues),
+                phase,
+            }));
+        });
+    });
+}
+async function abortableDelay(ms, signal) {
+    let timer;
+    try {
+        await raceWithAbort(() => new Promise((resolve) => {
+            timer = setTimeout(resolve, ms);
+        }), signal);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function responseErrorFields(payload) {
+    return {
+        errorId: typeof payload.errorId === "number" ? payload.errorId : undefined,
+        errorCode: typeof payload.errorCode === "string" ? payload.errorCode : undefined,
+        errorDescription: typeof payload.errorDescription === "string" ? payload.errorDescription : undefined,
+    };
+}
+function parseCreateTaskResponse(payload) {
+    const taskId = payload.taskId;
+    return {
+        ...responseErrorFields(payload),
+        taskId: typeof taskId === "string" || typeof taskId === "number" ? taskId : undefined,
+    };
+}
+function parsePollResultResponse(payload) {
+    const solution = isJsonRecord(payload.solution) ? payload.solution : undefined;
+    return {
+        ...responseErrorFields(payload),
+        status: typeof payload.status === "string" ? payload.status : undefined,
+        solution: solution
+            ? { token: typeof solution.token === "string" ? solution.token : undefined }
+            : undefined,
+    };
+}
+function isAllocationExhausted(payload) {
+    const code = payload.errorCode?.toLowerCase() ?? "";
+    const description = payload.errorDescription?.toLowerCase() ?? "";
+    return (code === "error_zero_balance" ||
+        /(?:insufficient|zero|no|not enough)\s+(?:balance|funds|credit)/u.test(`${code} ${description}`));
+}
+function isNegativeVerdict(payload) {
+    return payload.errorCode?.toLowerCase() === "error_captcha_unsolvable";
+}
+function safeVendorDetail(value, sensitiveValues) {
+    const redacted = redactSensitiveText(value, sensitiveValues);
+    return containsSensitiveValue(redacted, sensitiveValues) ? "[REDACTED]" : redacted;
+}
+function vendorErrorDetails(payload, sensitiveValues) {
+    const errorCode = payload.errorCode?.trim();
+    const errorDescription = payload.errorDescription?.trim();
+    return {
+        ...(errorCode ? { errorCode: safeVendorDetail(errorCode, sensitiveValues) } : {}),
+        ...(errorDescription
+            ? { errorDescription: safeVendorDetail(payload.errorDescription ?? "", sensitiveValues) }
+            : {}),
+    };
+}
+function unavailableForPayload(payload, phase, sensitiveValues) {
+    const details = vendorErrorDetails(payload, sensitiveValues);
+    if (isNegativeVerdict(payload)) {
+        return new CapsolverVerdictError({ phase, ...details });
+    }
+    return new CapsolverUnavailableError(isAllocationExhausted(payload) ? "allocation_exhausted" : "transport_failure", { phase, ...details });
+}
+async function postJson(fetchImpl, url, body, signal, phase, sensitiveValues, parseResponse) {
+    const response = await raceWithAbort(() => fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        signal,
+        redirect: "error",
+    }), signal, phase, sensitiveValues);
+    let responseText;
+    try {
+        responseText = await raceWithAbort(() => response.text(), signal, phase, sensitiveValues);
+    }
+    catch (error) {
+        if (error instanceof ResolverVendorUnavailableError)
+            throw error;
+        throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+            cause: error,
+            phase,
+        });
+    }
+    let payload;
+    try {
+        payload = JSON.parse(responseText);
+    }
+    catch {
+        const contentType = response.headers.get("content-type");
+        throw new CapsolverUnavailableError("transport_failure", {
+            cause: sanitizedJsonParseCause(),
+            phase,
+            responseStatus: response.status,
+            responseContentType: contentType
+                ? safeVendorDetail(contentType.slice(0, 128), sensitiveValues)
+                : undefined,
+            responseLength: responseText.length,
+        });
+    }
+    if (!isJsonRecord(payload)) {
+        throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+            phase,
+        });
+    }
+    return { ok: response.ok, payload: parseResponse(payload) };
+}
+function endpoint(baseUrl, path) {
+    return `${baseUrl.replace(/\/+$/u, "")}/${path}`;
+}
+function spanErrorAttributes(error, phase) {
+    if (error instanceof ResolverVendorUnavailableError) {
+        return {
+            unavailability_reason: error.reason,
+            transport_phase: error.phase,
+            ...(error instanceof CapsolverUnavailableError
+                ? {
+                    vendor_error_code: error.errorCode,
+                    vendor_error_description: error.errorDescription,
+                    response_status: error.responseStatus,
+                    response_content_type: error.responseContentType,
+                    response_length: error.responseLength,
+                }
+                : {}),
+        };
+    }
+    if (error instanceof CapsolverVerdictError) {
+        return {
+            verdict_reason: error.reason,
+            transport_phase: error.phase,
+            vendor_error_code: error.errorCode,
+            vendor_error_description: error.errorDescription,
+        };
+    }
+    if (error instanceof CapsolverSolveTimeoutError) {
+        return {
+            unavailability_reason: "timeout",
+            transport_phase: phase,
+        };
+    }
+    return undefined;
+}
+export function createCapsolverResolverVendorAdapter(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const baseUrl = options.baseUrl ?? DEFAULT_CAPSOLVER_BASE_URL;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const now = options.now ?? Date.now;
+    const delay = options.delay ?? abortableDelay;
+    return {
+        id: CAPSOLVER_VENDOR_ID,
+        supports(kind) {
+            return resolverVendorSupports(CAPSOLVER_VENDOR_ID, kind);
+        },
+        async solve(challenge, _identity, callerSignal, traceRecorder) {
+            const apiKey = options.apiKey?.trim();
+            if (!apiKey) {
+                throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "missing_credentials", {
+                    phase: "create_task",
+                });
+            }
+            if (!resolverVendorSupports(CAPSOLVER_VENDOR_ID, challenge.kind)) {
+                throw new TypeError(`Capsolver resolver does not support ${challenge.kind}`);
+            }
+            if (challenge.kind !== "turnstile") {
+                throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "not_implemented", {
+                    phase: "create_task",
+                });
+            }
+            const sensitiveValues = [
+                apiKey,
+                challenge.pageUrl,
+                challenge.siteKey,
+                ...(challenge.action !== undefined ? [challenge.action] : []),
+                ...(challenge.cdata !== undefined ? [challenge.cdata] : []),
+            ];
+            assertResolverHostAllowed(challenge.pageUrl, options.allowedHosts);
+            callerSignal.throwIfAborted();
+            const solveController = new AbortController();
+            const onCallerAbort = () => solveController.abort(abortReason(callerSignal));
+            callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+            const timeout = options.now
+                ? undefined
+                : setTimeout(() => solveController.abort(new CapsolverSolveTimeoutError()), timeoutMs);
+            const startedAt = now();
+            let phase = "create_task";
+            try {
+                const createTask = async () => {
+                    const metadata = {
+                        ...(challenge.action !== undefined ? { action: challenge.action } : {}),
+                        ...(challenge.cdata !== undefined ? { cdata: challenge.cdata } : {}),
+                    };
+                    const createResult = await postJson(fetchImpl, endpoint(baseUrl, "createTask"), {
+                        clientKey: apiKey,
+                        task: {
+                            type: "AntiTurnstileTaskProxyLess",
+                            websiteURL: challenge.pageUrl,
+                            websiteKey: challenge.siteKey,
+                            ...(challenge.action !== undefined || challenge.cdata !== undefined
+                                ? { metadata }
+                                : {}),
+                        },
+                    }, solveController.signal, phase, sensitiveValues, parseCreateTaskResponse);
+                    const taskId = createResult.payload.taskId;
+                    if (!createResult.ok || createResult.payload.errorId !== 0 || taskId === undefined) {
+                        throw unavailableForPayload(createResult.payload, phase, sensitiveValues);
+                    }
+                    return taskId;
+                };
+                const taskId = traceRecorder
+                    ? await traceRecorder.runSpan("resolver.vendor.create_task", createTask, {
+                        attributes: {
+                            vendor: CAPSOLVER_VENDOR_ID,
+                            challenge_kind: challenge.kind,
+                        },
+                        onError: (error) => spanErrorAttributes(error, "create_task"),
+                    })
+                    : await createTask();
+                phase = "poll_result";
+                const pollResult = async () => {
+                    while (true) {
+                        callerSignal.throwIfAborted();
+                        const remainingMs = timeoutMs - (now() - startedAt);
+                        if (remainingMs <= 0)
+                            throw new CapsolverSolveTimeoutError();
+                        await delay(Math.min(pollIntervalMs, remainingMs), solveController.signal);
+                        callerSignal.throwIfAborted();
+                        if (now() - startedAt >= timeoutMs)
+                            throw new CapsolverSolveTimeoutError();
+                        const result = await postJson(fetchImpl, endpoint(baseUrl, "getTaskResult"), { clientKey: apiKey, taskId }, solveController.signal, phase, sensitiveValues, parsePollResultResponse);
+                        if (!result.ok || result.payload.errorId !== 0) {
+                            throw unavailableForPayload(result.payload, phase, sensitiveValues);
+                        }
+                        switch (result.payload.status) {
+                            case "idle":
+                            case "processing":
+                                continue;
+                            case "ready":
+                                break;
+                            default:
+                                throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", { phase });
+                        }
+                        const token = result.payload.solution?.token;
+                        if (!token?.trim()) {
+                            throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+                                phase,
+                            });
+                        }
+                        return { form: "token", token };
+                    }
+                };
+                return traceRecorder
+                    ? await traceRecorder.runSpan("resolver.vendor.poll_result", pollResult, {
+                        attributes: {
+                            vendor: CAPSOLVER_VENDOR_ID,
+                            challenge_kind: challenge.kind,
+                        },
+                        onError: (error) => spanErrorAttributes(error, "poll_result"),
+                    })
+                    : await pollResult();
+            }
+            catch (error) {
+                if (callerSignal.aborted)
+                    throw abortReason(callerSignal);
+                if (error instanceof CapsolverSolveTimeoutError ||
+                    solveController.signal.reason instanceof CapsolverSolveTimeoutError) {
+                    throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "timeout", {
+                        cause: error,
+                        phase,
+                    });
+                }
+                if (error instanceof ResolverVendorUnavailableError ||
+                    error instanceof ResolverChallengeVerdictError) {
+                    throw error;
+                }
+                throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+                    ...safeCauseOptions(error, sensitiveValues),
+                    phase,
+                });
+            }
+            finally {
+                if (timeout !== undefined)
+                    clearTimeout(timeout);
+                callerSignal.removeEventListener("abort", onCallerAbort);
+            }
+        },
+    };
+}

package/dist/runtime/resolver.js

@@ -4,6 +4,7 @@ import { ProviderError } from "../errors.js";
 import { getStealthProfile } from "../stealth/profiles.js";
 import { resolverChallengeAllowsDirectCache, resolverChallengeIsCacheable, resolverChallengeIsIdentityScoped, resolverChallengeIssuingIdentity, } from "./resolver-vendors/bindings.js";
 import { createBrowserResolverVendorAdapter } from "./resolver-vendors/browser.js";
+import { createCapsolverResolverVendorAdapter } from "./resolver-vendors/capsolver.js";
 import { assertResolverHostAllowed } from "./resolver-vendors/hosts.js";
 import { createTwoCaptchaResolverVendorAdapter } from "./resolver-vendors/twocaptcha.js";
 import { RESOLVER_VENDOR_CAPABILITIES, ResolverVendorUnavailableError, resolverVendorSupports, } from "./resolver-vendors/types.js";
@@ -61,6 +62,13 @@ const resolverAdapterRegistry = {
             timeoutMs,
         });
     },
+    capsolver(configuration, timeoutMs, allowedHosts) {
+        return createCapsolverResolverVendorAdapter({
+            allowedHosts,
+            apiKey: configuration,
+            timeoutMs,
+        });
+    },
     browser(configuration, timeoutMs, allowedHosts) {
         return createBrowserResolverVendorAdapter({
             allowedHosts,
@@ -104,7 +112,6 @@ export function swapResolverDefaultUserAgentForTests(resolver) {
 // This is the sole allowlist for declared vendors whose registry entry may be absent.
 // Remove a vendor here when its adapter is registered.
 const KNOWN_UNIMPLEMENTED_RESOLVER_VENDORS = new Set([
-    "capsolver",
     "capmonster",
     "custom",
 ]);

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.31",
+	"version": "2.2.0-beta.32",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/runtime/resolver-vendors/capsolver.ts

@@ -0,0 +1,563 @@
+import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
+import { redactSensitiveText } from "../request-options.js";
+import type { TraceRecorder } from "../trace.js";
+import { assertResolverHostAllowed } from "./hosts.js";
+import {
+	ResolverChallengeVerdictError,
+	type ResolverIdentity,
+	type ResolverVendorAdapter,
+	ResolverVendorUnavailableError,
+	type ResolverVendorUnavailableReason,
+	resolverVendorSupports,
+} from "./types.js";
+
+const CAPSOLVER_VENDOR_ID = "capsolver" as const;
+const DEFAULT_CAPSOLVER_BASE_URL = "https://api.capsolver.com";
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+type Delay = (ms: number, signal: AbortSignal) => Promise<void>;
+type CapsolverOperationPhase = "create_task" | "poll_result";
+
+export interface CapsolverResolverVendorOptions {
+	readonly apiKey?: string;
+	readonly timeoutMs?: number;
+	readonly pollIntervalMs?: number;
+	readonly allowedHosts: readonly string[];
+	readonly fetchImpl?: typeof fetch;
+	readonly baseUrl?: string;
+	/** Test-only clock override; supplying it disables the real-time deadline timer. */
+	readonly now?: () => number;
+	/** Test-only delay override used with `now` to exercise polling without sleeping. */
+	readonly delay?: Delay;
+}
+
+export interface CapsolverResolverVendorAdapter extends ResolverVendorAdapter {
+	readonly id: "capsolver";
+	solve(
+		challenge: ProviderChallenge,
+		identity: ResolverIdentity | undefined,
+		signal: AbortSignal,
+		traceRecorder?: TraceRecorder,
+	): Promise<Extract<ChallengeSolution, { readonly form: "token" }>>;
+}
+
+class CapsolverSolveTimeoutError extends Error {
+	constructor() {
+		super("Capsolver resolver solve budget elapsed");
+		this.name = "CapsolverSolveTimeoutError";
+	}
+}
+
+class CapsolverUnavailableError extends ResolverVendorUnavailableError {
+	readonly errorCode: string | undefined;
+	readonly errorDescription: string | undefined;
+	readonly responseStatus: number | undefined;
+	readonly responseContentType: string | undefined;
+	readonly responseLength: number | undefined;
+
+	constructor(
+		reason: ResolverVendorUnavailableReason,
+		options: {
+			readonly phase: CapsolverOperationPhase;
+			readonly cause?: unknown;
+			readonly errorCode?: string;
+			readonly errorDescription?: string;
+			readonly responseStatus?: number;
+			readonly responseContentType?: string;
+			readonly responseLength?: number;
+		},
+	) {
+		super(CAPSOLVER_VENDOR_ID, reason, options);
+		this.errorCode = options.errorCode;
+		this.errorDescription = options.errorDescription;
+		this.responseStatus = options.responseStatus;
+		this.responseContentType = options.responseContentType;
+		this.responseLength = options.responseLength;
+	}
+}
+
+type JsonRecord = Record<string, unknown>;
+
+interface CapsolverResponseErrorFields {
+	readonly errorId: number | undefined;
+	readonly errorCode: string | undefined;
+	readonly errorDescription: string | undefined;
+}
+
+interface CapsolverCreateTaskResponse extends CapsolverResponseErrorFields {
+	readonly taskId: string | number | undefined;
+}
+
+interface CapsolverPollResultResponse extends CapsolverResponseErrorFields {
+	readonly status: string | undefined;
+	readonly solution: { readonly token: string | undefined } | undefined;
+}
+
+class CapsolverVerdictError extends ResolverChallengeVerdictError {
+	readonly phase: CapsolverOperationPhase;
+	readonly errorCode: string | undefined;
+	readonly errorDescription: string | undefined;
+
+	constructor(options: {
+		readonly phase: CapsolverOperationPhase;
+		readonly errorCode?: string;
+		readonly errorDescription?: string;
+	}) {
+		super(CAPSOLVER_VENDOR_ID, "solve_failed", options);
+		this.phase = options.phase;
+		this.errorCode = options.errorCode;
+		this.errorDescription = options.errorDescription;
+	}
+}
+
+function isJsonRecord(value: unknown): value is JsonRecord {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function abortReason(signal: AbortSignal): unknown {
+	return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+
+function containsSensitiveValue(value: unknown, sensitiveValues: readonly string[]): boolean {
+	const secrets = sensitiveValues.filter((secret) => secret.length > 0);
+	if (secrets.length === 0) return false;
+	const seen = new Set<object>();
+
+	const inspect = (candidate: unknown): boolean => {
+		if (typeof candidate === "string") {
+			return secrets.some((secret) => candidate.includes(secret));
+		}
+		if (candidate === null || (typeof candidate !== "object" && typeof candidate !== "function")) {
+			return false;
+		}
+		if (seen.has(candidate)) return false;
+		seen.add(candidate);
+
+		try {
+			for (const property of Reflect.ownKeys(candidate)) {
+				if (typeof property === "string" && inspect(property)) return true;
+				const descriptor = Object.getOwnPropertyDescriptor(candidate, property);
+				if (!descriptor) return true;
+				if ("value" in descriptor && inspect(descriptor.value)) return true;
+				if (descriptor.get !== undefined || descriptor.set !== undefined) return true;
+			}
+		} catch {
+			return true;
+		}
+		return false;
+	};
+
+	return inspect(value);
+}
+
+function safeCauseOptions(
+	error: unknown,
+	sensitiveValues: readonly string[],
+): { readonly cause?: unknown } {
+	return containsSensitiveValue(error, sensitiveValues) ? {} : { cause: error };
+}
+
+function sanitizedJsonParseCause(): SyntaxError {
+	return new SyntaxError("Upstream response failed");
+}
+
+function raceWithAbort<T>(
+	operation: () => Promise<T>,
+	signal: AbortSignal,
+	phase?: CapsolverOperationPhase,
+	sensitiveValues: readonly string[] = [],
+): Promise<T> {
+	if (signal.aborted) return Promise.reject(abortReason(signal));
+
+	return new Promise<T>((resolve, reject) => {
+		const cleanup = () => signal.removeEventListener("abort", onAbort);
+		const onAbort = () => {
+			cleanup();
+			reject(abortReason(signal));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		operation().then(
+			(value) => {
+				cleanup();
+				resolve(value);
+			},
+			(error: unknown) => {
+				cleanup();
+				if (phase === undefined) {
+					reject(error);
+					return;
+				}
+				reject(
+					new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+						...safeCauseOptions(error, sensitiveValues),
+						phase,
+					}),
+				);
+			},
+		);
+	});
+}
+
+async function abortableDelay(ms: number, signal: AbortSignal): Promise<void> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	try {
+		await raceWithAbort(
+			() =>
+				new Promise<void>((resolve) => {
+					timer = setTimeout(resolve, ms);
+				}),
+			signal,
+		);
+	} finally {
+		if (timer !== undefined) clearTimeout(timer);
+	}
+}
+
+function responseErrorFields(payload: JsonRecord): CapsolverResponseErrorFields {
+	return {
+		errorId: typeof payload.errorId === "number" ? payload.errorId : undefined,
+		errorCode: typeof payload.errorCode === "string" ? payload.errorCode : undefined,
+		errorDescription:
+			typeof payload.errorDescription === "string" ? payload.errorDescription : undefined,
+	};
+}
+
+function parseCreateTaskResponse(payload: JsonRecord): CapsolverCreateTaskResponse {
+	const taskId = payload.taskId;
+	return {
+		...responseErrorFields(payload),
+		taskId: typeof taskId === "string" || typeof taskId === "number" ? taskId : undefined,
+	};
+}
+
+function parsePollResultResponse(payload: JsonRecord): CapsolverPollResultResponse {
+	const solution = isJsonRecord(payload.solution) ? payload.solution : undefined;
+	return {
+		...responseErrorFields(payload),
+		status: typeof payload.status === "string" ? payload.status : undefined,
+		solution: solution
+			? { token: typeof solution.token === "string" ? solution.token : undefined }
+			: undefined,
+	};
+}
+
+function isAllocationExhausted(payload: CapsolverResponseErrorFields): boolean {
+	const code = payload.errorCode?.toLowerCase() ?? "";
+	const description = payload.errorDescription?.toLowerCase() ?? "";
+	return (
+		code === "error_zero_balance" ||
+		/(?:insufficient|zero|no|not enough)\s+(?:balance|funds|credit)/u.test(`${code} ${description}`)
+	);
+}
+
+function isNegativeVerdict(payload: CapsolverResponseErrorFields): boolean {
+	return payload.errorCode?.toLowerCase() === "error_captcha_unsolvable";
+}
+
+function safeVendorDetail(value: string, sensitiveValues: readonly string[]): string {
+	const redacted = redactSensitiveText(value, sensitiveValues);
+	return containsSensitiveValue(redacted, sensitiveValues) ? "[REDACTED]" : redacted;
+}
+
+function vendorErrorDetails(
+	payload: CapsolverResponseErrorFields,
+	sensitiveValues: readonly string[],
+): { readonly errorCode?: string; readonly errorDescription?: string } {
+	const errorCode = payload.errorCode?.trim();
+	const errorDescription = payload.errorDescription?.trim();
+	return {
+		...(errorCode ? { errorCode: safeVendorDetail(errorCode, sensitiveValues) } : {}),
+		...(errorDescription
+			? { errorDescription: safeVendorDetail(payload.errorDescription ?? "", sensitiveValues) }
+			: {}),
+	};
+}
+
+function unavailableForPayload(
+	payload: CapsolverResponseErrorFields,
+	phase: CapsolverOperationPhase,
+	sensitiveValues: readonly string[],
+): ResolverVendorUnavailableError | ResolverChallengeVerdictError {
+	const details = vendorErrorDetails(payload, sensitiveValues);
+	if (isNegativeVerdict(payload)) {
+		return new CapsolverVerdictError({ phase, ...details });
+	}
+	return new CapsolverUnavailableError(
+		isAllocationExhausted(payload) ? "allocation_exhausted" : "transport_failure",
+		{ phase, ...details },
+	);
+}
+
+async function postJson<TResponse>(
+	fetchImpl: typeof fetch,
+	url: string,
+	body: JsonRecord,
+	signal: AbortSignal,
+	phase: CapsolverOperationPhase,
+	sensitiveValues: readonly string[],
+	parseResponse: (payload: JsonRecord) => TResponse,
+): Promise<{ readonly ok: boolean; readonly payload: TResponse }> {
+	const response = await raceWithAbort(
+		() =>
+			fetchImpl(url, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify(body),
+				signal,
+				redirect: "error",
+			}),
+		signal,
+		phase,
+		sensitiveValues,
+	);
+
+	let responseText: string;
+	try {
+		responseText = await raceWithAbort(() => response.text(), signal, phase, sensitiveValues);
+	} catch (error) {
+		if (error instanceof ResolverVendorUnavailableError) throw error;
+		throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+			cause: error,
+			phase,
+		});
+	}
+
+	let payload: unknown;
+	try {
+		payload = JSON.parse(responseText);
+	} catch {
+		const contentType = response.headers.get("content-type");
+		throw new CapsolverUnavailableError("transport_failure", {
+			cause: sanitizedJsonParseCause(),
+			phase,
+			responseStatus: response.status,
+			responseContentType: contentType
+				? safeVendorDetail(contentType.slice(0, 128), sensitiveValues)
+				: undefined,
+			responseLength: responseText.length,
+		});
+	}
+	if (!isJsonRecord(payload)) {
+		throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+			phase,
+		});
+	}
+	return { ok: response.ok, payload: parseResponse(payload) };
+}
+
+function endpoint(baseUrl: string, path: string): string {
+	return `${baseUrl.replace(/\/+$/u, "")}/${path}`;
+}
+
+function spanErrorAttributes(
+	error: unknown,
+	phase: CapsolverOperationPhase,
+): Record<string, unknown> | undefined {
+	if (error instanceof ResolverVendorUnavailableError) {
+		return {
+			unavailability_reason: error.reason,
+			transport_phase: error.phase,
+			...(error instanceof CapsolverUnavailableError
+				? {
+						vendor_error_code: error.errorCode,
+						vendor_error_description: error.errorDescription,
+						response_status: error.responseStatus,
+						response_content_type: error.responseContentType,
+						response_length: error.responseLength,
+					}
+				: {}),
+		};
+	}
+	if (error instanceof CapsolverVerdictError) {
+		return {
+			verdict_reason: error.reason,
+			transport_phase: error.phase,
+			vendor_error_code: error.errorCode,
+			vendor_error_description: error.errorDescription,
+		};
+	}
+	if (error instanceof CapsolverSolveTimeoutError) {
+		return {
+			unavailability_reason: "timeout",
+			transport_phase: phase,
+		};
+	}
+	return undefined;
+}
+
+export function createCapsolverResolverVendorAdapter(
+	options: CapsolverResolverVendorOptions,
+): CapsolverResolverVendorAdapter {
+	const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+	const baseUrl = options.baseUrl ?? DEFAULT_CAPSOLVER_BASE_URL;
+	const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const now = options.now ?? Date.now;
+	const delay = options.delay ?? abortableDelay;
+
+	return {
+		id: CAPSOLVER_VENDOR_ID,
+
+		supports(kind) {
+			return resolverVendorSupports(CAPSOLVER_VENDOR_ID, kind);
+		},
+
+		async solve(challenge, _identity, callerSignal, traceRecorder) {
+			const apiKey = options.apiKey?.trim();
+			if (!apiKey) {
+				throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "missing_credentials", {
+					phase: "create_task",
+				});
+			}
+			if (!resolverVendorSupports(CAPSOLVER_VENDOR_ID, challenge.kind)) {
+				throw new TypeError(`Capsolver resolver does not support ${challenge.kind}`);
+			}
+			if (challenge.kind !== "turnstile") {
+				throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "not_implemented", {
+					phase: "create_task",
+				});
+			}
+			const sensitiveValues = [
+				apiKey,
+				challenge.pageUrl,
+				challenge.siteKey,
+				...(challenge.action !== undefined ? [challenge.action] : []),
+				...(challenge.cdata !== undefined ? [challenge.cdata] : []),
+			];
+
+			assertResolverHostAllowed(challenge.pageUrl, options.allowedHosts);
+			callerSignal.throwIfAborted();
+
+			const solveController = new AbortController();
+			const onCallerAbort = () => solveController.abort(abortReason(callerSignal));
+			callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+			const timeout = options.now
+				? undefined
+				: setTimeout(() => solveController.abort(new CapsolverSolveTimeoutError()), timeoutMs);
+			const startedAt = now();
+			let phase: CapsolverOperationPhase = "create_task";
+
+			try {
+				const createTask = async () => {
+					const metadata = {
+						...(challenge.action !== undefined ? { action: challenge.action } : {}),
+						...(challenge.cdata !== undefined ? { cdata: challenge.cdata } : {}),
+					};
+					const createResult = await postJson(
+						fetchImpl,
+						endpoint(baseUrl, "createTask"),
+						{
+							clientKey: apiKey,
+							task: {
+								type: "AntiTurnstileTaskProxyLess",
+								websiteURL: challenge.pageUrl,
+								websiteKey: challenge.siteKey,
+								...(challenge.action !== undefined || challenge.cdata !== undefined
+									? { metadata }
+									: {}),
+							},
+						},
+						solveController.signal,
+						phase,
+						sensitiveValues,
+						parseCreateTaskResponse,
+					);
+					const taskId = createResult.payload.taskId;
+					if (!createResult.ok || createResult.payload.errorId !== 0 || taskId === undefined) {
+						throw unavailableForPayload(createResult.payload, phase, sensitiveValues);
+					}
+					return taskId;
+				};
+				const taskId = traceRecorder
+					? await traceRecorder.runSpan("resolver.vendor.create_task", createTask, {
+							attributes: {
+								vendor: CAPSOLVER_VENDOR_ID,
+								challenge_kind: challenge.kind,
+							},
+							onError: (error) => spanErrorAttributes(error, "create_task"),
+						})
+					: await createTask();
+
+				phase = "poll_result";
+				const pollResult = async () => {
+					while (true) {
+						callerSignal.throwIfAborted();
+						const remainingMs = timeoutMs - (now() - startedAt);
+						if (remainingMs <= 0) throw new CapsolverSolveTimeoutError();
+						await delay(Math.min(pollIntervalMs, remainingMs), solveController.signal);
+						callerSignal.throwIfAborted();
+						if (now() - startedAt >= timeoutMs) throw new CapsolverSolveTimeoutError();
+
+						const result = await postJson(
+							fetchImpl,
+							endpoint(baseUrl, "getTaskResult"),
+							{ clientKey: apiKey, taskId },
+							solveController.signal,
+							phase,
+							sensitiveValues,
+							parsePollResultResponse,
+						);
+						if (!result.ok || result.payload.errorId !== 0) {
+							throw unavailableForPayload(result.payload, phase, sensitiveValues);
+						}
+						switch (result.payload.status) {
+							case "idle":
+							case "processing":
+								continue;
+							case "ready":
+								break;
+							default:
+								throw new ResolverVendorUnavailableError(
+									CAPSOLVER_VENDOR_ID,
+									"transport_failure",
+									{ phase },
+								);
+						}
+
+						const token = result.payload.solution?.token;
+						if (!token?.trim()) {
+							throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+								phase,
+							});
+						}
+						return { form: "token" as const, token };
+					}
+				};
+				return traceRecorder
+					? await traceRecorder.runSpan("resolver.vendor.poll_result", pollResult, {
+							attributes: {
+								vendor: CAPSOLVER_VENDOR_ID,
+								challenge_kind: challenge.kind,
+							},
+							onError: (error) => spanErrorAttributes(error, "poll_result"),
+						})
+					: await pollResult();
+			} catch (error) {
+				if (callerSignal.aborted) throw abortReason(callerSignal);
+				if (
+					error instanceof CapsolverSolveTimeoutError ||
+					solveController.signal.reason instanceof CapsolverSolveTimeoutError
+				) {
+					throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "timeout", {
+						cause: error,
+						phase,
+					});
+				}
+				if (
+					error instanceof ResolverVendorUnavailableError ||
+					error instanceof ResolverChallengeVerdictError
+				) {
+					throw error;
+				}
+				throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+					...safeCauseOptions(error, sensitiveValues),
+					phase,
+				});
+			} finally {
+				if (timeout !== undefined) clearTimeout(timeout);
+				callerSignal.removeEventListener("abort", onCallerAbort);
+			}
+		},
+	};
+}

package/src/runtime/resolver.ts

@@ -24,6 +24,7 @@ import {
 	resolverChallengeIssuingIdentity,
 } from "./resolver-vendors/bindings.js";
 import { createBrowserResolverVendorAdapter } from "./resolver-vendors/browser.js";
+import { createCapsolverResolverVendorAdapter } from "./resolver-vendors/capsolver.js";
 import { assertResolverHostAllowed } from "./resolver-vendors/hosts.js";
 import { createTwoCaptchaResolverVendorAdapter } from "./resolver-vendors/twocaptcha.js";
 import {
@@ -196,6 +197,13 @@ const resolverAdapterRegistry: Partial<Record<ProviderResolverVendor, ResolverAd
 			timeoutMs,
 		});
 	},
+	capsolver(configuration, timeoutMs, allowedHosts) {
+		return createCapsolverResolverVendorAdapter({
+			allowedHosts,
+			apiKey: configuration,
+			timeoutMs,
+		});
+	},
 	browser(configuration, timeoutMs, allowedHosts) {
 		return createBrowserResolverVendorAdapter({
 			allowedHosts,
@@ -246,7 +254,6 @@ export function swapResolverDefaultUserAgentForTests(
 // This is the sole allowlist for declared vendors whose registry entry may be absent.
 // Remove a vendor here when its adapter is registered.
 const KNOWN_UNIMPLEMENTED_RESOLVER_VENDORS: ReadonlySet<ProviderResolverVendor> = new Set([
-	"capsolver",
 	"capmonster",
 	"custom",
 ]);