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

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

@@ -0,0 +1,368 @@
+import { assertResolverHostAllowed } from "./hosts.js";
+import { ResolverChallengeVerdictError, ResolverVendorUnavailableError, 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 {
+            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 {
+            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) {
+            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 !== "recaptcha_v2" && challenge.kind !== "aws_waf") {
+                throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "not_implemented", {
+                    phase: "create_task",
+                });
+            }
+            if (challenge.kind === "aws_waf" &&
+                (!challenge.siteKey?.trim() ||
+                    !challenge.captchaScript?.trim() ||
+                    !challenge.context?.trim() ||
+                    !challenge.iv?.trim())) {
+                throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "not_implemented", {
+                    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 ?? {}),
+                        }
+                        : {
+                            type: proxy ? "RecaptchaV2Task" : "RecaptchaV2TaskProxyless",
+                            websiteURL: challenge.pageUrl,
+                            websiteKey: challenge.siteKey,
+                            isInvisible: false,
+                            ...(identity ? { userAgent: identity.userAgent } : {}),
+                            ...(proxy ?? {}),
+                        };
+                    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: {
+                            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();
+                        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 });
+                        }
+                        return { form: "token", token };
+                    }
+                };
+                return traceRecorder
+                    ? await traceRecorder.runSpan("resolver.vendor.poll_result", pollResult, {
+                        attributes: {
+                            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,83 @@
+import type { ChallengeSolution, ProviderChallenge, ProviderChallengeKind, ProviderResolverVendor } from "../../types.js";
+import type { TraceRecorder } from "../trace.js";
+export declare const RESOLVER_VENDOR_CAPABILITIES: {
+    readonly browser: readonly ["aws_waf", "cloudflare_interstitial"];
+    readonly "2captcha": readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "cloudflare_interstitial", "aws_waf", "akamai_sec_cpt", "akamai_sensor"];
+    readonly capsolver: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "cloudflare_interstitial", "aws_waf"];
+    readonly capmonster: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha"];
+    readonly custom: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "cloudflare_interstitial", "aws_waf", "akamai_sec_cpt", "akamai_sensor"];
+};
+export declare function resolverVendorSupports(vendor: ProviderResolverVendor, kind: ProviderChallengeKind): boolean;
+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 {
+    /**
+     * Bound to the resolved proxy lease and client profile.
+     * Implementations MUST NOT follow redirects and MUST return the initial redirect 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";
+    }): 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;
+        }[];
+    }>;
+}
+export interface ResolverVendorAdapter {
+    readonly id: ProviderResolverVendor;
+    readonly requiresTransport?: boolean | ((kind: ProviderChallengeKind) => boolean);
+    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): Promise<ChallengeSolution>;
+}
+export type ResolverVendorUnavailableReason = "missing_credentials" | "missing_proxy_identity" | "missing_client_profile" | "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;
+    /** 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 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,69 @@
+export const RESOLVER_VENDOR_CAPABILITIES = {
+    browser: ["aws_waf", "cloudflare_interstitial"],
+    "2captcha": [
+        "turnstile",
+        "recaptcha_v2",
+        "recaptcha_v3",
+        "hcaptcha",
+        "cloudflare_interstitial",
+        "aws_waf",
+        "akamai_sec_cpt",
+        "akamai_sensor",
+    ],
+    capsolver: [
+        "turnstile",
+        "recaptcha_v2",
+        "recaptcha_v3",
+        "hcaptcha",
+        "cloudflare_interstitial",
+        "aws_waf",
+    ],
+    capmonster: ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha"],
+    custom: [
+        "turnstile",
+        "recaptcha_v2",
+        "recaptcha_v3",
+        "hcaptcha",
+        "cloudflare_interstitial",
+        "aws_waf",
+        "akamai_sec_cpt",
+        "akamai_sensor",
+    ],
+};
+export function resolverVendorSupports(vendor, kind) {
+    return RESOLVER_VENDOR_CAPABILITIES[vendor].includes(kind);
+}
+export class ResolverVendorUnavailableError extends Error {
+    vendor;
+    reason;
+    upstreamHost;
+    phase;
+    round;
+    constructor(vendor, reason, options = {}) {
+        super(`Resolver vendor ${vendor} is unavailable: ${reason}`);
+        this.vendor = vendor;
+        this.reason = reason;
+        this.name = "ResolverVendorUnavailableError";
+        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;
+        }
+    }
+}

package/dist/runtime/resolver.d.ts

@@ -0,0 +1,59 @@
+import { type ProxyResolutionOptions } from "../config/loader.js";
+import type { ChallengeSolution, ProviderCache, ProviderChallenge, ProviderChallengeKind, ProviderProxyMode, ProviderResolverConfig, ProviderResolverVendor, ResolverContext } from "../types.js";
+import { type ResolverIdentity, type ResolverVendorAdapter, type ResolverVendorTransport } from "./resolver-vendors/types.js";
+import type { TraceRecorder } from "./trace.js";
+export { createUnsupportedResolverClient, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver-shared.js";
+export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./resolver-config.js";
+type EnvLike = Record<string, string | undefined>;
+type ResolverChainClient = ResolverContext & {
+    solve(challenge: ProviderChallenge, signal?: AbortSignal, traceRecorder?: TraceRecorder): Promise<ChallengeSolution>;
+};
+export interface ResolverRuntimeOptions {
+    readonly allowedHosts?: readonly string[];
+    readonly cache?: ProviderCache;
+    /** Inputs for SDK-owned lazy proxy resolution. The SDK never accepts a caller-built identity. */
+    readonly proxyIntent?: {
+        readonly mode: ProviderProxyMode;
+        readonly upstream: NonNullable<ProxyResolutionOptions["upstream"]>;
+        readonly affinityKey?: ProxyResolutionOptions["affinityKey"];
+        readonly telemetry?: ProxyResolutionOptions["telemetry"];
+        readonly userAgent?: string;
+    };
+    /** Server-owned context/proxy scope used only for identity-bound cache entries. */
+    readonly identityScope?: string;
+    /** SDK-owned transport already bound to the resolved proxy lease and client profile. */
+    readonly transport?: ResolverVendorTransport;
+    /** Creates an SDK-owned transport bound to the declared profile and server-owned scope. */
+    readonly createTransport?: (input: {
+        readonly clientProfile?: string;
+        /** Server-owned proxy/context scope; the SDK never accepts a caller-built identity. */
+        readonly identityScope?: string;
+    }) => ResolverVendorTransport;
+}
+export type ResolverInstrumentationMetadata = {
+    readonly target: ResolverContext;
+    readonly traceRecorder: TraceRecorder;
+};
+export type ResolverAdapterFactory = (configuration: string, timeoutMs: number, allowedHosts: readonly string[]) => ResolverVendorAdapter;
+export declare const RESOLVER_ADAPTER_REGISTRY: Partial<Readonly<Record<ProviderResolverVendor, ResolverAdapterFactory>>>;
+export declare function swapResolverAdapterFactoryForTests(vendor: ProviderResolverVendor, factory: ResolverAdapterFactory | undefined): () => void;
+/** Internal test seam; deliberately not re-exported from the package root. */
+export declare function swapResolverDefaultUserAgentForTests(resolver: (() => string | undefined) | undefined): () => void;
+/** Remove the cached entry for the exact solution object returned by this resolver. */
+export declare function invalidateResolverSolution(resolver: ResolverContext, challenge: ProviderChallenge, solution: ChallengeSolution): Promise<void>;
+export declare function createResolverClient(options: {
+    readonly kinds: readonly ProviderChallengeKind[];
+    readonly adapters: readonly ResolverVendorAdapter[];
+    readonly unavailableReason?: string;
+    readonly cache?: ProviderCache;
+    readonly identity?: ResolverIdentity;
+    readonly proxyIntent?: ResolverRuntimeOptions["proxyIntent"];
+    readonly transport?: ResolverVendorTransport;
+    readonly createTransport?: ResolverRuntimeOptions["createTransport"];
+    readonly clientProfile?: string;
+    readonly allowedHosts?: readonly string[];
+}): ResolverChainClient;
+export declare function bindResolverSignal(resolver: ResolverContext, defaultSignal: AbortSignal | undefined): ResolverContext;
+export declare function createResolverClientFromEnv(config: ProviderResolverConfig | undefined, env?: EnvLike, options?: ResolverRuntimeOptions): ResolverContext;
+/** Internal test seam; deliberately not re-exported from the package root. */
+export declare function createResolverClientFromEnvForTests(config: ProviderResolverConfig | undefined, env: EnvLike, options: ResolverRuntimeOptions, adapterFactories: Partial<Readonly<Record<ProviderResolverVendor, ResolverAdapterFactory>>>): ResolverContext;