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

package/dist/runtime/resolver-telemetry.d.ts

@@ -0,0 +1,135 @@
+import type { ProviderChallengeKind, ProviderResolverVendor } from "../types.js";
+import { type ClosedEnum, type TelemetryContributor } from "./request-telemetry.js";
+import type { ResolverVendorUnavailableReason } from "./resolver-vendors/types.js";
+/**
+ * Result of the resolver call. `solved` means the adapter returned a solution;
+ * for SBSD this means payload acceptance, even when `verified` is false.
+ * It does not assert that a later protected request succeeded. Stealth reports
+ * that verification separately through the refetch status and challenge outcome.
+ */
+export type ResolverTelemetryOutcome = "solved" | "cached" | "exhausted" | "aborted" | "error";
+export type ResolverTelemetryCacheStatus = "hit" | "miss" | "disabled" | "not_cacheable";
+export type ResolverTelemetryIdentitySource = "declared" | "defaulted" | "none";
+export type ResolverTelemetryPhase = "create_task" | "poll_result" | "cleanup" | "measure_ip" | "fetch_script" | "generate_payload" | "post_payload";
+export type ResolverTelemetryAttemptOutcome = "ok" | "error";
+export type ResolverTelemetryErrorClass = ResolverVendorUnavailableReason | "aborted" | "unexpected";
+export type ResolverTelemetryCacheWriteReason = "no_expires" | "not_cacheable" | "error";
+export type ResolverIdentityTelemetryEvent = {
+    readonly source: ResolverTelemetryIdentitySource;
+    readonly failure?: ResolverVendorUnavailableReason;
+};
+export type ResolverCacheReadTelemetryEvent = {
+    readonly status: ResolverTelemetryCacheStatus;
+    readonly challengeKind: ProviderChallengeKind;
+};
+export type ResolverCacheWriteTelemetryEvent = {
+    readonly written: boolean;
+    readonly reason?: ResolverTelemetryCacheWriteReason;
+};
+export type ResolverVendorAttemptTelemetryEvent = {
+    readonly vendor: ProviderResolverVendor;
+    readonly phase: ResolverTelemetryPhase;
+    readonly outcome: ResolverTelemetryAttemptOutcome;
+    readonly ms: number;
+    readonly pollCount?: number;
+    readonly errorClass?: ResolverTelemetryErrorClass;
+    readonly vendorErrorCode?: string;
+    readonly vendorErrorDescription?: string;
+    /** Operator-only diagnostics; free text is redacted, detached and bounded by the collector. */
+    readonly diagnostics?: {
+        readonly cause?: {
+            readonly name: string;
+            readonly message: string;
+        };
+        readonly upstreamHost?: string;
+        readonly missingFields?: readonly string[];
+        readonly round?: number;
+        /** One-based position in the supporting vendor chain. */
+        readonly attemptIndex?: number;
+        /** Actual adapter phase, including phases outside the header's closed enum. */
+        readonly phase?: string;
+    };
+};
+export type ResolverFailoverTelemetryEvent = {
+    readonly from: ProviderResolverVendor;
+    readonly to: ProviderResolverVendor;
+    readonly reason: ResolverVendorUnavailableReason;
+};
+export type ResolverOutcomeTelemetryEvent = {
+    readonly outcome: ResolverTelemetryOutcome;
+    readonly solveMs: number;
+    readonly challengeKind: ProviderChallengeKind;
+};
+export interface ResolverTelemetrySink {
+    recordIdentity(event: ResolverIdentityTelemetryEvent): void;
+    recordCacheRead(event: ResolverCacheReadTelemetryEvent): void;
+    recordCacheWrite(event: ResolverCacheWriteTelemetryEvent): void;
+    recordVendorAttempt(event: ResolverVendorAttemptTelemetryEvent): void;
+    recordFailover(event: ResolverFailoverTelemetryEvent): void;
+    recordOutcome(event: ResolverOutcomeTelemetryEvent): void;
+}
+export type ResolverAttemptSample = {
+    v: ProviderResolverVendor;
+    p: ResolverTelemetryPhase;
+    o: ResolverTelemetryAttemptOutcome;
+    ms: number;
+    c?: string;
+    e?: ResolverTelemetryErrorClass;
+    diagnostics?: ResolverVendorAttemptTelemetryEvent["diagnostics"];
+};
+export type ResolverTelemetryLogPayload = {
+    /** Adapter result; `solved` includes unverified payload acceptance. Read the protected refetch status/challenge outcome for verification. */
+    outcome?: ResolverTelemetryOutcome;
+    challengeKind?: ProviderChallengeKind;
+    cacheStatus?: ResolverTelemetryCacheStatus;
+    cacheWrite?: {
+        written: boolean;
+        reason?: ResolverTelemetryCacheWriteReason;
+    };
+    identitySource?: ResolverTelemetryIdentitySource;
+    identityFailure?: ResolverVendorUnavailableReason;
+    solveMs?: number;
+    attempts: number;
+    failovers: number;
+    vendorChain: ProviderResolverVendor[];
+    vendorUsed?: ProviderResolverVendor;
+    pollCount: number;
+    attemptSamples?: ResolverAttemptSample[];
+    attemptSamplesDropped?: number;
+    lastVendorErrorDescription?: string;
+};
+export type ResolverTelemetryHeaderPayload = {
+    /** Same adapter-result semantics as the log outcome; `solved` does not imply protected-refetch success. */
+    outcome?: ClosedEnum<ResolverTelemetryOutcome>;
+    cacheStatus?: ClosedEnum<ResolverTelemetryCacheStatus>;
+    solveMs?: number;
+    attempts: number;
+    failovers: number;
+    vendorUsed?: ClosedEnum<ProviderResolverVendor>;
+    vendorChain: ClosedEnum<ProviderResolverVendor>[];
+    pollCount: number;
+    identitySource?: ClosedEnum<ResolverTelemetryIdentitySource>;
+    attemptSamples?: {
+        v: ClosedEnum<ProviderResolverVendor>;
+        p: ClosedEnum<ResolverTelemetryPhase>;
+        o: ClosedEnum<ResolverTelemetryAttemptOutcome>;
+        ms: number;
+        c?: ClosedEnum<string>;
+    }[];
+};
+export declare function boundedText(value: string, redact?: (text: string) => string): string;
+export declare class ResolverTelemetryCollector implements ResolverTelemetrySink, TelemetryContributor<ResolverTelemetryLogPayload, ResolverTelemetryHeaderPayload> {
+    #private;
+    readonly key: "resolver";
+    constructor(options?: {
+        redact?: (text: string) => string;
+    });
+    recordIdentity(event: ResolverIdentityTelemetryEvent): void;
+    recordCacheRead(event: ResolverCacheReadTelemetryEvent): void;
+    recordCacheWrite(event: ResolverCacheWriteTelemetryEvent): void;
+    recordVendorAttempt(event: ResolverVendorAttemptTelemetryEvent): void;
+    recordFailover(_event: ResolverFailoverTelemetryEvent): void;
+    recordOutcome(event: ResolverOutcomeTelemetryEvent): void;
+    toLogPayload(): ResolverTelemetryLogPayload | undefined;
+    toHeaderPayload(log: ResolverTelemetryLogPayload): ResolverTelemetryHeaderPayload;
+}

package/dist/runtime/resolver-telemetry.js

@@ -0,0 +1,204 @@
+import { Buffer } from "node:buffer";
+import { closedEnum } from "./request-telemetry.js";
+const MAX_RESOLVER_ATTEMPT_SAMPLES = 24;
+const MAX_RESOLVER_VENDOR_CHAIN = 64;
+const MAX_DIAGNOSTIC_TEXT = 300;
+const MAX_MISSING_FIELDS = 24;
+const HEADER_TOKEN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/;
+function boundedInteger(value) {
+    return Math.max(0, Math.floor(Number.isFinite(value) ? value : 0));
+}
+export function boundedText(value, redact) {
+    let result = value;
+    try {
+        result = redact?.(value) ?? value;
+    }
+    catch {
+        return "[REDACTION_FAILED]";
+    }
+    // Copy code units through an independent UTF-16 buffer. A sliced string can
+    // otherwise keep a multi-megabyte vendor response alive in both JSC and V8.
+    // Preserve lone surrogates deliberately, including a pair split at the limit.
+    const length = Math.min(result.length, MAX_DIAGNOSTIC_TEXT);
+    const units = Buffer.alloc(length * 2);
+    for (let index = 0; index < length; index += 1) {
+        units.writeUInt16LE(result.charCodeAt(index), index * 2);
+    }
+    return units.toString("utf16le");
+}
+function boundedDiagnostics(diagnostics, redact) {
+    return {
+        ...(diagnostics.cause
+            ? {
+                cause: {
+                    name: boundedText(diagnostics.cause.name, redact),
+                    message: boundedText(diagnostics.cause.message, redact),
+                },
+            }
+            : {}),
+        ...(diagnostics.upstreamHost
+            ? { upstreamHost: boundedText(diagnostics.upstreamHost, redact) }
+            : {}),
+        ...(diagnostics.missingFields
+            ? {
+                missingFields: diagnostics.missingFields
+                    .slice(0, MAX_MISSING_FIELDS)
+                    .map((field) => boundedText(field, redact)),
+            }
+            : {}),
+        ...(diagnostics.round === undefined ? {} : { round: boundedInteger(diagnostics.round) }),
+        ...(diagnostics.attemptIndex === undefined
+            ? {}
+            : { attemptIndex: boundedInteger(diagnostics.attemptIndex) }),
+        ...(diagnostics.phase ? { phase: boundedText(diagnostics.phase, redact) } : {}),
+    };
+}
+export class ResolverTelemetryCollector {
+    key = "resolver";
+    #redact;
+    #identity;
+    #cacheRead;
+    #cacheWrite;
+    #outcome;
+    #attempts = 0;
+    #failovers = 0;
+    #pollCount = 0;
+    #vendorChain = [];
+    #vendorUsed;
+    #attemptSamples = [];
+    #attemptSamplesDropped = 0;
+    #lastVendorErrorDescription;
+    constructor(options = {}) {
+        this.#redact = options.redact;
+    }
+    recordIdentity(event) {
+        this.#identity = { ...event };
+    }
+    recordCacheRead(event) {
+        this.#cacheRead = { ...event };
+    }
+    recordCacheWrite(event) {
+        this.#cacheWrite = { ...event };
+    }
+    recordVendorAttempt(event) {
+        const ms = boundedInteger(event.ms);
+        const pollCount = event.pollCount === undefined ? 0 : boundedInteger(event.pollCount);
+        this.#pollCount += pollCount;
+        if (event.phase !== "cleanup") {
+            this.#attempts += 1;
+            if (this.#vendorChain.length < MAX_RESOLVER_VENDOR_CHAIN &&
+                this.#vendorChain.at(-1) !== event.vendor) {
+                this.#vendorChain.push(event.vendor);
+            }
+            if (event.outcome === "ok")
+                this.#vendorUsed = event.vendor;
+        }
+        if (this.#attemptSamples.length < MAX_RESOLVER_ATTEMPT_SAMPLES) {
+            this.#attemptSamples.push({
+                v: event.vendor,
+                p: event.phase,
+                o: event.outcome,
+                ms,
+                ...(event.vendorErrorCode ? { c: boundedText(event.vendorErrorCode, this.#redact) } : {}),
+                ...(event.errorClass ? { e: event.errorClass } : {}),
+                ...(event.diagnostics
+                    ? { diagnostics: boundedDiagnostics(event.diagnostics, this.#redact) }
+                    : {}),
+            });
+        }
+        else {
+            this.#attemptSamplesDropped += 1;
+        }
+        if (event.vendorErrorDescription) {
+            this.#lastVendorErrorDescription = boundedText(event.vendorErrorDescription, this.#redact);
+        }
+    }
+    recordFailover(_event) {
+        this.#failovers += 1;
+    }
+    recordOutcome(event) {
+        this.#outcome = { ...event, solveMs: boundedInteger(event.solveMs) };
+    }
+    toLogPayload() {
+        if (!this.#identity &&
+            !this.#cacheRead &&
+            !this.#cacheWrite &&
+            !this.#outcome &&
+            this.#attempts === 0 &&
+            this.#attemptSamples.length === 0 &&
+            this.#failovers === 0) {
+            return undefined;
+        }
+        return {
+            ...(this.#outcome
+                ? {
+                    outcome: this.#outcome.outcome,
+                    challengeKind: this.#outcome.challengeKind,
+                    solveMs: this.#outcome.solveMs,
+                }
+                : this.#cacheRead
+                    ? { challengeKind: this.#cacheRead.challengeKind }
+                    : {}),
+            ...(this.#cacheRead ? { cacheStatus: this.#cacheRead.status } : {}),
+            ...(this.#cacheWrite ? { cacheWrite: { ...this.#cacheWrite } } : {}),
+            ...(this.#identity
+                ? {
+                    identitySource: this.#identity.source,
+                    ...(this.#identity.failure ? { identityFailure: this.#identity.failure } : {}),
+                }
+                : {}),
+            attempts: this.#attempts,
+            failovers: this.#failovers,
+            vendorChain: [...this.#vendorChain],
+            ...(this.#vendorUsed ? { vendorUsed: this.#vendorUsed } : {}),
+            pollCount: this.#pollCount,
+            ...(this.#attemptSamples.length > 0
+                ? {
+                    attemptSamples: this.#attemptSamples.map((sample) => ({
+                        ...sample,
+                        ...(sample.diagnostics
+                            ? {
+                                diagnostics: {
+                                    ...sample.diagnostics,
+                                    ...(sample.diagnostics.cause
+                                        ? { cause: { ...sample.diagnostics.cause } }
+                                        : {}),
+                                    ...(sample.diagnostics.missingFields
+                                        ? { missingFields: [...sample.diagnostics.missingFields] }
+                                        : {}),
+                                },
+                            }
+                            : {}),
+                    })),
+                }
+                : {}),
+            ...(this.#attemptSamplesDropped > 0
+                ? { attemptSamplesDropped: this.#attemptSamplesDropped }
+                : {}),
+            ...(this.#lastVendorErrorDescription
+                ? { lastVendorErrorDescription: this.#lastVendorErrorDescription }
+                : {}),
+        };
+    }
+    toHeaderPayload(log) {
+        const attemptSamples = log.attemptSamples?.map((sample) => ({
+            v: closedEnum(sample.v),
+            p: closedEnum(sample.p),
+            o: closedEnum(sample.o),
+            ms: sample.ms,
+            ...(sample.c && HEADER_TOKEN.test(sample.c) ? { c: closedEnum(sample.c) } : {}),
+        }));
+        return {
+            ...(log.outcome ? { outcome: closedEnum(log.outcome) } : {}),
+            ...(log.cacheStatus ? { cacheStatus: closedEnum(log.cacheStatus) } : {}),
+            ...(log.solveMs === undefined ? {} : { solveMs: log.solveMs }),
+            attempts: log.attempts,
+            failovers: log.failovers,
+            ...(log.vendorUsed ? { vendorUsed: closedEnum(log.vendorUsed) } : {}),
+            vendorChain: log.vendorChain.map((vendor) => closedEnum(vendor)),
+            pollCount: log.pollCount,
+            ...(log.identitySource ? { identitySource: closedEnum(log.identitySource) } : {}),
+            ...(attemptSamples && attemptSamples.length > 0 ? { attemptSamples } : {}),
+        };
+    }
+}

package/dist/runtime/resolver-usage.d.ts

@@ -0,0 +1,32 @@
+import type { ProviderChallengeKind, ProviderResolverVendor } from "../types.js";
+import type { ResolverPaidUsageContext } from "./resolver-vendors/types.js";
+import type { TraceRecorder } from "./trace.js";
+export declare const RESOLVER_PAID_USAGE_SPAN = "resolver.usage";
+export type ResolverPaidUsageOutcome = "success" | "vendor_error" | "timeout" | "abandoned";
+export type ResolverPaidUsageEndpoint = "capsolver:create_task" | "twocaptcha:create_task" | "hyper:ip" | "hyper:sbsd_create";
+/**
+ * How one call to the endpoint is counted. `metered` endpoints are the vendors' task or
+ * payload creation calls: the SDK counts one unit per call (the vendor ledger stays
+ * authoritative for refunds of failed tasks). Hyper's `/ip` reflector is authenticated
+ * but has no published price, so it is recorded with 0 units and `billing: "unconfirmed"`
+ * rather than invented as a paid unit; the span still proves the call was made.
+ */
+export type ResolverPaidUsageBilling = "metered" | "unconfirmed";
+/**
+ * Records one `resolver.usage` span around a paid vendor call. Callers validate credentials
+ * and transport first, so a span means a potentially billable request was attempted (a
+ * failed create the vendor may still bill is a span too). Without a trace recorder the call
+ * still runs; the lost billing record is warned once per warn sink.
+ */
+export declare function recordPaidResolverCreate<T>(options: {
+    readonly traceRecorder?: TraceRecorder;
+    readonly vendor: ProviderResolverVendor;
+    readonly kind: ProviderChallengeKind;
+    readonly endpoint: ResolverPaidUsageEndpoint;
+    /** 1-based round for endpoints called more than once per solve (Hyper payload rounds). */
+    readonly round?: number;
+    readonly signal: AbortSignal;
+    readonly usage?: ResolverPaidUsageContext;
+    readonly warn?: (message: string) => void;
+    readonly create: () => Promise<T>;
+}): Promise<T>;

package/dist/runtime/resolver-usage.js

@@ -0,0 +1,54 @@
+import { resolverSpanAttributes } from "./resolver-span-attributes.js";
+export const RESOLVER_PAID_USAGE_SPAN = "resolver.usage";
+const ENDPOINT_BILLING = {
+    "capsolver:create_task": { billable_units: 1, billing: "metered" },
+    "twocaptcha:create_task": { billable_units: 1, billing: "metered" },
+    "hyper:ip": { billable_units: 0, billing: "unconfirmed" },
+    "hyper:sbsd_create": { billable_units: 1, billing: "metered" },
+};
+function errorOutcome(error, signal) {
+    const signalReason = signal.reason;
+    const errorName = error instanceof Error ? error.name : "";
+    const reasonName = signalReason instanceof Error ? signalReason.name : "";
+    const unavailableReason = error?.reason;
+    if (unavailableReason === "timeout" ||
+        /timeout/iu.test(errorName) ||
+        /timeout/iu.test(reasonName)) {
+        return "timeout";
+    }
+    if (signal.aborted)
+        return "abandoned";
+    return "vendor_error";
+}
+const warnedSinks = new WeakSet();
+/**
+ * Records one `resolver.usage` span around a paid vendor call. Callers validate credentials
+ * and transport first, so a span means a potentially billable request was attempted (a
+ * failed create the vendor may still bill is a span too). Without a trace recorder the call
+ * still runs; the lost billing record is warned once per warn sink.
+ */
+export async function recordPaidResolverCreate(options) {
+    if (!options.traceRecorder) {
+        const warn = options.warn ?? console.warn;
+        if (!warnedSinks.has(warn)) {
+            warnedSinks.add(warn);
+            warn(`[provider-sdk] Paid resolver call ${options.endpoint} ran without a trace recorder; its resolver.usage record is lost (reported once).`);
+        }
+        return options.create();
+    }
+    const baseAttributes = resolverSpanAttributes({
+        vendor: options.vendor,
+        challenge_kind: options.kind,
+        endpoint: options.endpoint,
+        ...ENDPOINT_BILLING[options.endpoint],
+        // Only the resolver chain knows the vendor's position; a direct adapter call has none.
+        ...(options.usage ? { vendor_index: options.usage.vendorIndex } : {}),
+        ...(options.round === undefined ? {} : { round: options.round }),
+        resolver_identity_scope: options.usage?.resolverIdentityScope,
+    });
+    return options.traceRecorder.runSpan(RESOLVER_PAID_USAGE_SPAN, options.create, {
+        attributes: baseAttributes,
+        onSuccess: () => resolverSpanAttributes({ outcome: "success" }),
+        onError: (error) => resolverSpanAttributes({ outcome: errorOutcome(error, options.signal) }),
+    });
+}

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

@@ -0,0 +1,53 @@
+import type { ProviderChallenge } from "../../types.js";
+import type { ResolverIssuingIdentity } from "./types.js";
+export declare const RESOLVER_CHALLENGE_BINDINGS: {
+    readonly turnstile: {
+        readonly cacheable: false;
+        readonly identityBinding: "none";
+        readonly directCacheable: false;
+    };
+    readonly recaptcha_v2: {
+        readonly cacheable: false;
+        readonly identityBinding: "none";
+        readonly directCacheable: false;
+    };
+    readonly recaptcha_v3: {
+        readonly cacheable: false;
+        readonly identityBinding: "none";
+        readonly directCacheable: false;
+    };
+    readonly hcaptcha: {
+        readonly cacheable: false;
+        readonly identityBinding: "none";
+        readonly directCacheable: false;
+    };
+    readonly cloudflare_interstitial: {
+        readonly cacheable: true;
+        readonly identityBinding: "identity_scoped";
+        readonly directCacheable: true;
+    };
+    readonly aws_waf: {
+        readonly cacheable: true;
+        readonly identityBinding: "portable";
+        readonly directCacheable: true;
+    };
+    readonly akamai_sec_cpt: {
+        readonly cacheable: true;
+        readonly identityBinding: "identity_scoped";
+        readonly directCacheable: false;
+    };
+    readonly akamai_sensor: {
+        readonly cacheable: true;
+        readonly identityBinding: "identity_scoped";
+        readonly directCacheable: false;
+    };
+    readonly akamai_sbsd: {
+        readonly cacheable: false;
+        readonly identityBinding: "identity_scoped";
+        readonly directCacheable: false;
+    };
+};
+export declare function resolverChallengeIsCacheable(challenge: ProviderChallenge): boolean;
+export declare function resolverChallengeAllowsDirectCache(challenge: ProviderChallenge): boolean;
+export declare function resolverChallengeIsIdentityScoped(challenge: ProviderChallenge): boolean;
+export declare function resolverChallengeIssuingIdentity(challenge: ProviderChallenge, identity: ResolverIssuingIdentity): ResolverIssuingIdentity;

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

@@ -0,0 +1,45 @@
+// An IP-bound artifact minted without any recorded egress identity is unsafe to
+// share. The Akamai kinds therefore reject direct caching, while Cloudflare
+// keeps its pre-existing direct-cache behavior pending measurement.
+export const RESOLVER_CHALLENGE_BINDINGS = {
+    turnstile: { cacheable: false, identityBinding: "none", directCacheable: false },
+    recaptcha_v2: { cacheable: false, identityBinding: "none", directCacheable: false },
+    recaptcha_v3: { cacheable: false, identityBinding: "none", directCacheable: false },
+    hcaptcha: { cacheable: false, identityBinding: "none", directCacheable: false },
+    cloudflare_interstitial: {
+        cacheable: true,
+        identityBinding: "identity_scoped",
+        directCacheable: true,
+    },
+    aws_waf: { cacheable: true, identityBinding: "portable", directCacheable: true },
+    akamai_sec_cpt: {
+        cacheable: true,
+        identityBinding: "identity_scoped",
+        directCacheable: false,
+    },
+    akamai_sensor: {
+        cacheable: true,
+        identityBinding: "identity_scoped",
+        directCacheable: false,
+    },
+    akamai_sbsd: {
+        cacheable: false,
+        identityBinding: "identity_scoped",
+        directCacheable: false,
+    },
+};
+export function resolverChallengeIsCacheable(challenge) {
+    return RESOLVER_CHALLENGE_BINDINGS[challenge.kind].cacheable;
+}
+export function resolverChallengeAllowsDirectCache(challenge) {
+    return RESOLVER_CHALLENGE_BINDINGS[challenge.kind].directCacheable;
+}
+export function resolverChallengeIsIdentityScoped(challenge) {
+    return RESOLVER_CHALLENGE_BINDINGS[challenge.kind].identityBinding === "identity_scoped";
+}
+export function resolverChallengeIssuingIdentity(challenge, identity) {
+    if (RESOLVER_CHALLENGE_BINDINGS[challenge.kind].identityBinding === "portable") {
+        return { userAgent: identity.userAgent };
+    }
+    return identity;
+}

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

@@ -0,0 +1,24 @@
+import type { BrowserClient, ChallengeSolution, ProviderChallenge } from "../../types.js";
+import { type BrowserClientOptions } from "../browser.js";
+import type { TraceRecorder } from "../trace.js";
+import type { BrowserTelemetrySink } from "../browser-telemetry.js";
+import { type ResolverIdentity, type ResolverVendorAdapter } from "./types.js";
+type BrowserClientFactory = (options: BrowserClientOptions) => BrowserClient;
+/** Internal test seam; deliberately not re-exported from the package root. */
+export declare function swapBrowserResolverClientFactoryForTests(factory: BrowserClientFactory | undefined): () => void;
+export interface BrowserResolverVendorOptions {
+    readonly cdpUrl?: string;
+    readonly timeoutMs: number;
+    readonly pollIntervalMs?: number;
+    readonly allowedHosts: readonly string[];
+    readonly createClient?: BrowserClientFactory;
+    readonly telemetry?: BrowserTelemetrySink;
+}
+export interface BrowserResolverVendorAdapter extends ResolverVendorAdapter {
+    readonly id: "browser";
+    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder): Promise<Extract<ChallengeSolution, {
+        readonly form: "cookies";
+    }>>;
+}
+export declare function createBrowserResolverVendorAdapter(options: BrowserResolverVendorOptions): BrowserResolverVendorAdapter;
+export {};