@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

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

@@ -0,0 +1,425 @@
+import { recordPaidResolverCreate } from "../resolver-usage.js";
+import { resolverSpanAttributes } from "../resolver-span-attributes.js";
+import { assertResolverHostAllowed } from "./hosts.js";
+import { ResolverChallengeVerdictError, ResolverVendorUnavailableError, recordResolverVendorPoll, resolverVendorSupports, } from "./types.js";
+const TWOCAPTCHA_VENDOR_ID = "2captcha";
+const DEFAULT_TWOCAPTCHA_BASE_URL = "https://api.2captcha.com";
+const DEFAULT_POLL_INTERVAL_MS = 3_000;
+const DEFAULT_TIMEOUT_MS = 180_000;
+class TwoCaptchaSolveTimeoutError extends Error {
+    constructor() {
+        super("2captcha resolver solve budget elapsed");
+        this.name = "TwoCaptchaSolveTimeoutError";
+    }
+}
+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 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(TWOCAPTCHA_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 parseProxyConfiguration(proxyUrl) {
+    try {
+        const url = new URL(proxyUrl);
+        const protocol = url.protocol.slice(0, -1).toLowerCase();
+        const proxyType = protocol === "socks4" || protocol === "socks5"
+            ? protocol
+            : protocol === "http" || protocol === "https"
+                ? "http"
+                : undefined;
+        const defaultPort = proxyType === "http" ? 80 : 1080;
+        const proxyPort = Number(url.port || defaultPort);
+        if (!proxyType || !url.hostname || !Number.isInteger(proxyPort) || proxyPort <= 0) {
+            return undefined;
+        }
+        const proxyLogin = url.username ? decodeURIComponent(url.username) : undefined;
+        const proxyPassword = url.password ? decodeURIComponent(url.password) : undefined;
+        return {
+            proxyType,
+            proxyAddress: url.hostname,
+            proxyPort,
+            ...(proxyLogin ? { proxyLogin } : {}),
+            ...(proxyPassword ? { proxyPassword } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function errorText(payload, key) {
+    const value = payload[key];
+    return typeof value === "string" ? value : "";
+}
+function isAllocationExhausted(payload) {
+    const code = errorText(payload, "errorCode").toLowerCase();
+    const description = errorText(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 errorText(payload, "errorCode").toLowerCase() === "error_captcha_unsolvable";
+}
+function unavailableForPayload(payload, phase) {
+    if (isNegativeVerdict(payload)) {
+        return new ResolverChallengeVerdictError(TWOCAPTCHA_VENDOR_ID, "solve_failed");
+    }
+    return new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, isAllocationExhausted(payload) ? "allocation_exhausted" : "transport_failure", { phase });
+}
+async function postJson(fetchImpl, url, body, signal, phase, sensitiveValues) {
+    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);
+    }
+    catch (error) {
+        if (error instanceof ResolverVendorUnavailableError)
+            throw error;
+        throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
+            cause: error,
+            phase,
+        });
+    }
+    let payload;
+    try {
+        payload = JSON.parse(responseText);
+    }
+    catch {
+        // JSON parse errors may contain response-body excerpts, so do not retain them as causes.
+        throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
+            phase,
+        });
+    }
+    if (!isJsonRecord(payload)) {
+        throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
+            phase,
+        });
+    }
+    return { ok: response.ok, payload };
+}
+function taskIdFrom(payload) {
+    const taskId = payload.taskId;
+    return typeof taskId === "string" || typeof taskId === "number" ? taskId : undefined;
+}
+function tokenFrom(payload, challenge) {
+    const solution = payload.solution;
+    if (!isJsonRecord(solution))
+        return undefined;
+    if (challenge.kind === "aws_waf") {
+        return typeof solution.existing_token === "string" ? solution.existing_token : undefined;
+    }
+    if (typeof solution.gRecaptchaResponse === "string")
+        return solution.gRecaptchaResponse;
+    return typeof solution.token === "string" ? solution.token : undefined;
+}
+function endpoint(baseUrl, path) {
+    return `${baseUrl.replace(/\/+$/u, "")}/${path}`;
+}
+function spanErrorAttributes(error, phase) {
+    if (error instanceof ResolverVendorUnavailableError) {
+        return resolverSpanAttributes({
+            unavailability_reason: error.reason,
+            transport_phase: error.phase,
+        });
+    }
+    // The solve budget raises TwoCaptchaSolveTimeoutError inside the spanned closure and
+    // the outer catch converts it only after the span has been finalized, so the span has
+    // to recognize it here or slow solves lose exactly the attribution these spans add.
+    if (error instanceof TwoCaptchaSolveTimeoutError) {
+        return resolverSpanAttributes({
+            unavailability_reason: "timeout",
+            transport_phase: phase,
+        });
+    }
+    return undefined;
+}
+export function createTwoCaptchaResolverVendorAdapter(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const baseUrl = options.baseUrl ?? DEFAULT_TWOCAPTCHA_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: TWOCAPTCHA_VENDOR_ID,
+        supports(kind) {
+            return resolverVendorSupports(TWOCAPTCHA_VENDOR_ID, kind);
+        },
+        async solve(challenge, identity, callerSignal, traceRecorder, _transport, usage) {
+            const apiKey = options.apiKey?.trim();
+            if (!apiKey) {
+                throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "missing_credentials", {
+                    phase: "create_task",
+                });
+            }
+            if (!resolverVendorSupports(TWOCAPTCHA_VENDOR_ID, challenge.kind)) {
+                throw new TypeError(`2captcha resolver does not support ${challenge.kind}`);
+            }
+            if (challenge.kind === "aws_waf") {
+                const missingFields = [
+                    ...(challenge.siteKey?.trim() ? [] : ["siteKey"]),
+                    ...(challenge.captchaScript?.trim() ? [] : ["captchaScript"]),
+                    ...(challenge.context?.trim() ? [] : ["context"]),
+                    ...(challenge.iv?.trim() ? [] : ["iv"]),
+                ];
+                if (missingFields.length > 0) {
+                    throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "missing_challenge_input", {
+                        missingFields,
+                        phase: "create_task",
+                    });
+                }
+            }
+            if (challenge.kind === "recaptcha_v3" && challenge.minScore === undefined) {
+                throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "missing_challenge_input", {
+                    missingFields: ["minScore"],
+                    phase: "create_task",
+                });
+            }
+            assertResolverHostAllowed(challenge.pageUrl, options.allowedHosts);
+            callerSignal.throwIfAborted();
+            const proxy = identity ? parseProxyConfiguration(identity.proxyUrl) : undefined;
+            if (identity && !proxy) {
+                throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
+                    phase: "create_task",
+                });
+            }
+            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 TwoCaptchaSolveTimeoutError()), timeoutMs);
+            const startedAt = now();
+            let phase = "create_task";
+            try {
+                const createTask = async () => {
+                    const task = challenge.kind === "aws_waf"
+                        ? {
+                            type: proxy ? "AmazonTask" : "AmazonTaskProxyless",
+                            websiteURL: challenge.pageUrl,
+                            websiteKey: challenge.siteKey,
+                            captchaScript: challenge.captchaScript,
+                            context: challenge.context,
+                            iv: challenge.iv,
+                            ...(identity ? { userAgent: identity.userAgent } : {}),
+                            ...(proxy ?? {}),
+                        }
+                        : challenge.kind === "recaptcha_v2"
+                            ? {
+                                type: proxy ? "RecaptchaV2Task" : "RecaptchaV2TaskProxyless",
+                                websiteURL: challenge.pageUrl,
+                                websiteKey: challenge.siteKey,
+                                isInvisible: false,
+                                ...(identity ? { userAgent: identity.userAgent } : {}),
+                                ...(proxy ?? {}),
+                            }
+                            : challenge.kind === "recaptcha_v3"
+                                ? {
+                                    type: "RecaptchaV3TaskProxyless",
+                                    websiteURL: challenge.pageUrl,
+                                    websiteKey: challenge.siteKey,
+                                    minScore: challenge.minScore,
+                                    pageAction: challenge.action,
+                                    ...(identity ? { userAgent: identity.userAgent } : {}),
+                                }
+                                : challenge.kind === "hcaptcha"
+                                    ? {
+                                        type: proxy ? "HCaptchaTask" : "HCaptchaTaskProxyless",
+                                        websiteURL: challenge.pageUrl,
+                                        websiteKey: challenge.siteKey,
+                                        ...(identity ? { userAgent: identity.userAgent } : {}),
+                                        ...(proxy ?? {}),
+                                    }
+                                    : challenge.kind === "turnstile"
+                                        ? {
+                                            type: proxy ? "TurnstileTask" : "TurnstileTaskProxyless",
+                                            websiteURL: challenge.pageUrl,
+                                            websiteKey: challenge.siteKey,
+                                            ...(challenge.action !== undefined ? { action: challenge.action } : {}),
+                                            ...(challenge.cdata !== undefined ? { data: challenge.cdata } : {}),
+                                            ...(identity ? { userAgent: identity.userAgent } : {}),
+                                            ...(proxy ?? {}),
+                                        }
+                                        : // `resolverVendorSupports` above already rejected every kind this
+                                            // adapter does not build a task for, so this branch is unreachable.
+                                            (() => {
+                                                throw new TypeError(`2captcha resolver does not support ${challenge.kind}`);
+                                            })();
+                    return await recordPaidResolverCreate({
+                        traceRecorder,
+                        vendor: TWOCAPTCHA_VENDOR_ID,
+                        kind: challenge.kind,
+                        endpoint: "twocaptcha:create_task",
+                        signal: solveController.signal,
+                        usage,
+                        create: async () => {
+                            const createResult = await postJson(fetchImpl, endpoint(baseUrl, "createTask"), { clientKey: apiKey, task }, solveController.signal, phase, [apiKey]);
+                            const taskId = taskIdFrom(createResult.payload);
+                            if (!createResult.ok || createResult.payload.errorId !== 0 || taskId === undefined) {
+                                throw unavailableForPayload(createResult.payload, phase);
+                            }
+                            return taskId;
+                        },
+                    });
+                };
+                const taskId = traceRecorder
+                    ? await traceRecorder.runSpan("resolver.vendor.create_task", createTask, {
+                        attributes: resolverSpanAttributes({
+                            vendor: TWOCAPTCHA_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 TwoCaptchaSolveTimeoutError();
+                        await delay(Math.min(pollIntervalMs, remainingMs), solveController.signal);
+                        callerSignal.throwIfAborted();
+                        if (now() - startedAt >= timeoutMs)
+                            throw new TwoCaptchaSolveTimeoutError();
+                        recordResolverVendorPoll(traceRecorder);
+                        const pollResult = await postJson(fetchImpl, endpoint(baseUrl, "getTaskResult"), { clientKey: apiKey, taskId }, solveController.signal, phase, [apiKey]);
+                        if (!pollResult.ok || pollResult.payload.errorId !== 0) {
+                            throw unavailableForPayload(pollResult.payload, phase);
+                        }
+                        if (pollResult.payload.status === "processing")
+                            continue;
+                        if (pollResult.payload.status !== "ready") {
+                            throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
+                                phase,
+                            });
+                        }
+                        const token = tokenFrom(pollResult.payload, challenge);
+                        if (!token?.trim()) {
+                            throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
+                                phase,
+                            });
+                        }
+                        // AWS WAF remains a token solution here, so resolver cookie caching does not apply.
+                        return { form: "token", token };
+                    }
+                };
+                return traceRecorder
+                    ? await traceRecorder.runSpan("resolver.vendor.poll_result", pollResult, {
+                        attributes: resolverSpanAttributes({
+                            vendor: TWOCAPTCHA_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 TwoCaptchaSolveTimeoutError ||
+                    solveController.signal.reason instanceof TwoCaptchaSolveTimeoutError) {
+                    throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "timeout", {
+                        cause: error,
+                        phase,
+                    });
+                }
+                if (error instanceof ResolverVendorUnavailableError ||
+                    error instanceof ResolverChallengeVerdictError) {
+                    throw error;
+                }
+                throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
+                    ...safeCauseOptions(error, [apiKey]),
+                    phase,
+                });
+            }
+            finally {
+                if (timeout !== undefined)
+                    clearTimeout(timeout);
+                callerSignal.removeEventListener("abort", onCallerAbort);
+            }
+        },
+    };
+}

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

@@ -0,0 +1,125 @@
+import type { ChallengeSolution, ProviderChallenge, ProviderChallengeKind, ProviderResolverConfig, ProviderResolverVendor } from "../../types.js";
+import type { TraceRecorder } from "../trace.js";
+/** Internal chain-runner hook; vendor adapters never receive the telemetry sink itself. */
+export declare function recordResolverVendorPoll(traceRecorder: TraceRecorder | undefined): void;
+export declare function attachResolverVendorPollObserver(traceRecorder: TraceRecorder, observer: () => void): TraceRecorder;
+export declare const RESOLVER_VENDOR_CAPABILITIES: {
+    readonly browser: readonly ["aws_waf", "cloudflare_interstitial"];
+    readonly "2captcha": readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "aws_waf"];
+    readonly capsolver: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "cloudflare_interstitial", "aws_waf"];
+    readonly capmonster: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha"];
+    readonly hypersolutions: readonly ["akamai_sbsd"];
+    readonly custom: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "cloudflare_interstitial", "aws_waf", "akamai_sec_cpt", "akamai_sensor", "akamai_sbsd"];
+};
+/**
+ * SDK-owned fallback policy for hosted resolver vendors. Capability support is
+ * applied separately, so each provider receives only vendors that support one
+ * or more of its declared challenge kinds.
+ */
+export declare const DEFAULT_RESOLVER_VENDOR_PREFERENCE: readonly ["capsolver", "2captcha", "hypersolutions"];
+export declare function resolverVendorSupports(vendor: ProviderResolverVendor, kind: ProviderChallengeKind): boolean;
+/** Resolves an explicit provider override or the SDK-owned default vendor chain. */
+export declare function resolveProviderResolverVendors(config: ProviderResolverConfig): readonly ProviderResolverVendor[];
+export interface ResolverIdentity {
+    readonly proxyUrl: string;
+    readonly userAgent: string;
+}
+export interface ResolverIssuingIdentity {
+    /** Absent when the adapter genuinely solved without a proxy. */
+    readonly proxyUrl?: string;
+    readonly userAgent: string;
+}
+export interface ResolverVendorTransport {
+    /**
+     * Exact stable upstream headers owned by the proxy/profile-bound transport.
+     * This does not include dynamic Cookie headers; the transport injects those from its jar.
+     * Adapter requests do not receive these headers implicitly and must forward
+     * them when their measured protocol requires session-header continuity.
+     */
+    readonly sessionHeaders?: Readonly<Record<string, string>>;
+    /**
+     * Read a cookie from the transport's bound jar for the supplied URL. Responses
+     * returned by `fetch` MUST already have been applied to that jar before this
+     * method is called. Profile-bound adapters fail closed when this seam is absent.
+     */
+    readonly getCookie?: (name: string, url: string) => string | undefined;
+    /** Implementations MUST NOT follow redirects and must return the initial response. */
+    fetch(url: string, init: {
+        method: "GET" | "POST";
+        headers?: Readonly<Record<string, string>>;
+        body?: string;
+        signal: AbortSignal;
+        /** Implementations MUST honor manual redirect handling when the SDK guard sets it. */
+        redirect?: "manual";
+        /** Maximum UTF-8 response body size; implementations must stop reading at this bound. */
+        maxBodyBytes?: number;
+    }): Promise<{
+        readonly status: number;
+        readonly headers: Readonly<Record<string, string>>;
+        readonly body: string;
+        /** Cookies observed on the response, including cache-relevant attributes. */
+        readonly cookies: readonly {
+            readonly name: string;
+            readonly value: string;
+            /** Epoch seconds. A session cookie must be undefined, never CDP's -1 sentinel. */
+            readonly expires?: number;
+            readonly httpOnly: boolean;
+            readonly secure: boolean;
+            readonly domain?: string;
+            readonly path?: string;
+            readonly sameSite?: string;
+        }[];
+    }>;
+}
+/** Metering context the resolver chain hands each vendor adapter for its paid calls. */
+export type ResolverPaidUsageContext = {
+    /** 1-based position of the vendor in the provider's declared resolver chain. */
+    readonly vendorIndex: number;
+    /** SHA-256 scope digest; never the raw affinity, proxy URL, cookie, or IP. */
+    readonly resolverIdentityScope?: string;
+};
+export interface ResolverVendorAdapter {
+    readonly id: ProviderResolverVendor;
+    readonly requiresTransport?: boolean | ((kind: ProviderChallengeKind) => boolean);
+    /**
+     * Exact SDK-owned service hosts this adapter may reach through its bound transport,
+     * in addition to the provider's `allowedHosts`. Every host must appear in the
+     * SDK-owned `RESOLVER_VENDOR_TRANSPORT_HOSTS` entry for `id`; the chain rejects any
+     * other declaration with `RESOLVER_VENDOR_HOST_NOT_ALLOWED`, whoever supplied the
+     * adapter. The transport handed to `solve` is revoked once `solve` settles.
+     */
+    readonly transportAllowedHosts?: readonly string[];
+    supports(kind: ProviderChallengeKind): boolean;
+    /** Identity the adapter actually used, reported after a successful solve. */
+    getIssuingIdentity?(solution: ChallengeSolution, requestedIdentity: ResolverIdentity | undefined, challenge: ProviderChallenge): ResolverIssuingIdentity | undefined;
+    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder, transport?: ResolverVendorTransport, usage?: ResolverPaidUsageContext): Promise<ChallengeSolution>;
+}
+export type ResolverVendorUnavailableReason = "missing_credentials" | "missing_proxy_identity" | "missing_client_profile" | "missing_challenge_input" | "missing_transport" | "allocation_exhausted" | "transport_failure" | "timeout" | "not_implemented";
+export type ResolverChallengeVerdictReason = "human_puzzle" | "solve_failed";
+type ResolverErrorOptions = {
+    /** Raw cause; adapters must not place bodies, cookies, headers, credentials, or proxy URLs here. */
+    readonly cause?: unknown;
+    /** Names of challenge fields required by this adapter but absent from this call's input. */
+    readonly missingFields?: readonly string[];
+    /** Upstream hostname only; never a URL. */
+    readonly upstreamHost?: string;
+    /** Adapter-defined sensor-loop phase, such as fetch_script or post_sensor. */
+    readonly phase?: string;
+    /** One-based sensor-loop round when known. */
+    readonly round?: number;
+};
+export declare class ResolverVendorUnavailableError extends Error {
+    readonly vendor: ProviderResolverVendor;
+    readonly reason: ResolverVendorUnavailableReason;
+    readonly missingFields?: readonly string[];
+    readonly upstreamHost?: string;
+    readonly phase?: string;
+    readonly round?: number;
+    constructor(vendor: ProviderResolverVendor, reason: ResolverVendorUnavailableReason, options?: ResolverErrorOptions);
+}
+export declare class ResolverChallengeVerdictError extends Error {
+    readonly vendor: ProviderResolverVendor;
+    readonly reason: ResolverChallengeVerdictReason;
+    constructor(vendor: ProviderResolverVendor, reason: ResolverChallengeVerdictReason, options?: ResolverErrorOptions);
+}
+export {};

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

@@ -0,0 +1,106 @@
+const RESOLVER_VENDOR_POLL_OBSERVER = Symbol.for("@apifuse/provider-sdk/runtime/resolver-vendor-poll-observer");
+/** Internal chain-runner hook; vendor adapters never receive the telemetry sink itself. */
+export function recordResolverVendorPoll(traceRecorder) {
+    traceRecorder?.[RESOLVER_VENDOR_POLL_OBSERVER]?.();
+}
+export function attachResolverVendorPollObserver(traceRecorder, observer) {
+    Object.defineProperty(traceRecorder, RESOLVER_VENDOR_POLL_OBSERVER, { value: observer });
+    return traceRecorder;
+}
+export const RESOLVER_VENDOR_CAPABILITIES = {
+    browser: ["aws_waf", "cloudflare_interstitial"],
+    // Every kind listed per vendor is implemented by that vendor's adapter; the
+    // per-adapter "agrees with every declared capability" tests iterate this
+    // table, so adding a kind here without an implementation fails the suite.
+    // 2captcha omits `cloudflare_interstitial` and every Akamai kind: its API
+    // offers no measured task type for them, so declaring them
+    // would route challenges to a vendor that can only refuse.
+    "2captcha": ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "aws_waf"],
+    capsolver: [
+        "turnstile",
+        "recaptcha_v2",
+        "recaptcha_v3",
+        "hcaptcha",
+        "cloudflare_interstitial",
+        "aws_waf",
+    ],
+    capmonster: ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha"],
+    // Hyper's /sbsd envelope is measured. Its sensor endpoint is deliberately
+    // omitted until that separate protocol is implemented and verified.
+    hypersolutions: ["akamai_sbsd"],
+    custom: [
+        "turnstile",
+        "recaptcha_v2",
+        "recaptcha_v3",
+        "hcaptcha",
+        "cloudflare_interstitial",
+        "aws_waf",
+        "akamai_sec_cpt",
+        "akamai_sensor",
+        "akamai_sbsd",
+    ],
+};
+/**
+ * SDK-owned fallback policy for hosted resolver vendors. Capability support is
+ * applied separately, so each provider receives only vendors that support one
+ * or more of its declared challenge kinds.
+ */
+export const DEFAULT_RESOLVER_VENDOR_PREFERENCE = [
+    "capsolver",
+    "2captcha",
+    "hypersolutions",
+];
+export function resolverVendorSupports(vendor, kind) {
+    return RESOLVER_VENDOR_CAPABILITIES[vendor].includes(kind);
+}
+/** Resolves an explicit provider override or the SDK-owned default vendor chain. */
+export function resolveProviderResolverVendors(config) {
+    if (config.vendors !== undefined)
+        return config.vendors;
+    return DEFAULT_RESOLVER_VENDOR_PREFERENCE.filter((vendor) => config.kinds.some((kind) => resolverVendorSupports(vendor, kind)));
+}
+export class ResolverVendorUnavailableError extends Error {
+    vendor;
+    reason;
+    missingFields;
+    upstreamHost;
+    phase;
+    round;
+    constructor(vendor, reason, options = {}) {
+        const missingFields = reason === "missing_challenge_input"
+            ? options.missingFields?.filter((field) => /^[A-Za-z][A-Za-z0-9_]*$/u.test(field))
+            : undefined;
+        super(reason === "missing_challenge_input" &&
+            missingFields !== undefined &&
+            missingFields.length > 0
+            ? `Resolver vendor ${vendor} cannot use incomplete challenge input; missing fields: ${missingFields.join(", ")}`
+            : `Resolver vendor ${vendor} is unavailable: ${reason}`);
+        this.vendor = vendor;
+        this.reason = reason;
+        this.name = "ResolverVendorUnavailableError";
+        if (missingFields !== undefined && missingFields.length > 0) {
+            this.missingFields = Object.freeze([...missingFields]);
+        }
+        if (options.cause !== undefined) {
+            this.cause = options.cause;
+        }
+        this.upstreamHost = options.upstreamHost;
+        this.phase = options.phase;
+        this.round = options.round;
+    }
+}
+export class ResolverChallengeVerdictError extends Error {
+    vendor;
+    reason;
+    constructor(vendor, reason, options = {}) {
+        super(reason === "solve_failed"
+            ? `Resolver vendor ${vendor} attempted the challenge but did not solve it`
+            : `Resolver vendor ${vendor} returned a challenge verdict: ${reason}`);
+        this.vendor = vendor;
+        this.reason = reason;
+        this.name = "ResolverChallengeVerdictError";
+        if (options.cause !== undefined) {
+            this.cause = options.cause;
+        }
+    }
+}