@apifuse/provider-sdk 2.2.0-beta.57 → 2.2.0-beta.59

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

@@ -1,6 +1,6 @@
 import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
 import type { TraceRecorder } from "../trace.js";
-import { type ResolverIdentity, type ResolverVendorAdapter } from "./types.js";
+import { type ResolverIdentity, type ResolverPaidUsageContext, type ResolverVendorAdapter, type ResolverVendorTransport } from "./types.js";
 type Delay = (ms: number, signal: AbortSignal) => Promise<void>;
 export interface CapsolverResolverVendorOptions {
     readonly apiKey?: string;
@@ -16,7 +16,7 @@ export interface CapsolverResolverVendorOptions {
 }
 export interface CapsolverResolverVendorAdapter extends ResolverVendorAdapter {
     readonly id: "capsolver";
-    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder): Promise<ChallengeSolution>;
+    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder, transport?: ResolverVendorTransport, usage?: ResolverPaidUsageContext): Promise<ChallengeSolution>;
 }
 export declare function createCapsolverResolverVendorAdapter(options: CapsolverResolverVendorOptions): CapsolverResolverVendorAdapter;
 export {};

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

@@ -1,8 +1,9 @@
 import { getStealthProfile } from "../../stealth/profiles.js";
 import { redactSensitiveText } from "../request-options.js";
 import { DEFAULT_STEALTH_PROFILE } from "../stealth.js";
+import { recordPaidResolverCreate } from "../resolver-usage.js";
 import { assertResolverHostAllowed } from "./hosts.js";
-import { ResolverChallengeVerdictError, ResolverVendorUnavailableError, resolverVendorSupports, } from "./types.js";
+import { ResolverChallengeVerdictError, ResolverVendorUnavailableError, recordResolverVendorPoll, 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;
@@ -304,7 +305,7 @@ export function createCapsolverResolverVendorAdapter(options) {
         supports(kind) {
             return resolverVendorSupports(CAPSOLVER_VENDOR_ID, kind);
         },
-        async solve(challenge, identity, callerSignal, traceRecorder) {
+        async solve(challenge, identity, callerSignal, traceRecorder, _transport, usage) {
             const apiKey = options.apiKey?.trim();
             if (!apiKey) {
                 throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "missing_credentials", {
@@ -416,12 +417,22 @@ export function createCapsolverResolverVendorAdapter(options) {
                                             : (() => {
                                                 throw new TypeError(`Capsolver resolver does not support ${challenge.kind}`);
                                             })();
-                    const createResult = await postJson(fetchImpl, endpoint(baseUrl, "createTask"), { clientKey: apiKey, task }, 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;
+                    return await recordPaidResolverCreate({
+                        traceRecorder,
+                        vendor: CAPSOLVER_VENDOR_ID,
+                        kind: challenge.kind,
+                        endpoint: "capsolver:create_task",
+                        signal: solveController.signal,
+                        usage,
+                        create: async () => {
+                            const createResult = await postJson(fetchImpl, endpoint(baseUrl, "createTask"), { clientKey: apiKey, task }, 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, {
@@ -443,6 +454,7 @@ export function createCapsolverResolverVendorAdapter(options) {
                         callerSignal.throwIfAborted();
                         if (now() - startedAt >= timeoutMs)
                             throw new CapsolverSolveTimeoutError();
+                        recordResolverVendorPoll(traceRecorder);
                         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);
@@ -460,7 +472,7 @@ export function createCapsolverResolverVendorAdapter(options) {
                         }
                         const solutionValue = challenge.kind === "aws_waf"
                             ? result.payload.solution?.cookie
-                            : result.payload.solution?.token ?? result.payload.solution?.gRecaptchaResponse;
+                            : (result.payload.solution?.token ?? result.payload.solution?.gRecaptchaResponse);
                         if (challenge.kind === "cloudflare_interstitial") {
                             const cookies = result.payload.solution?.cookies;
                             const clearance = cookies?.cf_clearance ?? solutionValue;

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

@@ -0,0 +1,27 @@
+import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
+import type { TraceRecorder } from "../trace.js";
+import { type ResolverIdentity, type ResolverPaidUsageContext, type ResolverVendorAdapter, type ResolverVendorTransport } from "./types.js";
+/**
+ * Only the observed-IP reflector rides the bound transport: Hyper must see the
+ * egress address the upstream will see. The payload-generation POST carries no
+ * identity and goes direct, as in the measured zozotown source.
+ */
+declare const HYPER_TRANSPORT_HOSTS: readonly ["ip.hypersolutions.co"];
+export interface HypersolutionsResolverVendorOptions {
+    readonly apiKey?: string;
+    readonly timeoutMs?: number;
+    readonly allowedHosts: readonly string[];
+    /** Direct egress used only for the Hyper payload-generation POST. */
+    readonly fetchImpl?: typeof fetch;
+}
+export type AkamaiSbsdChallengeSolution = Extract<ChallengeSolution, {
+    readonly form: "cookie_state";
+}>;
+export interface HypersolutionsResolverVendorAdapter extends ResolverVendorAdapter {
+    readonly id: "hypersolutions";
+    readonly requiresTransport: true;
+    readonly transportAllowedHosts: typeof HYPER_TRANSPORT_HOSTS;
+    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder, transport?: ResolverVendorTransport, usage?: ResolverPaidUsageContext): Promise<AkamaiSbsdChallengeSolution>;
+}
+export declare function createHypersolutionsResolverVendorAdapter(options: HypersolutionsResolverVendorOptions): HypersolutionsResolverVendorAdapter;
+export {};

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

@@ -0,0 +1,369 @@
+import { isIP } from "node:net";
+import { recordPaidResolverCreate } from "../resolver-usage.js";
+import { assertResolverHostAllowed } from "./hosts.js";
+import { ResolverChallengeVerdictError, ResolverVendorUnavailableError, } from "./types.js";
+const HYPERSOLUTIONS_VENDOR_ID = "hypersolutions";
+const HYPER_SBSD_URL = "https://akm.hypersolutions.co/sbsd";
+const HYPER_IP_URL = "https://ip.hypersolutions.co/ip";
+/**
+ * Only the observed-IP reflector rides the bound transport: Hyper must see the
+ * egress address the upstream will see. The payload-generation POST carries no
+ * identity and goes direct, as in the measured zozotown source.
+ */
+const HYPER_TRANSPORT_HOSTS = ["ip.hypersolutions.co"];
+const IP_RESPONSE_MAX_BYTES = 4_096;
+/** Measured bound shared by the script, the Hyper envelope, and the payload submission. */
+const BODY_MAX_BYTES = 1_000_000;
+function headerValue(headers, name) {
+    const target = name.toLowerCase();
+    return Object.entries(headers)
+        .find(([header]) => header.toLowerCase() === target)?.[1]
+        ?.trim();
+}
+function declaredLengthExceeds(declared, maxBytes) {
+    return declared !== undefined && /^\d+$/u.test(declared) && BigInt(declared) > BigInt(maxBytes);
+}
+function transportFailure(phase, cause) {
+    return new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "transport_failure", {
+        phase,
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+function assertBoundedBody(response, maxBytes, phase) {
+    if (declaredLengthExceeds(headerValue(response.headers, "content-length"), maxBytes) ||
+        new TextEncoder().encode(response.body).byteLength > maxBytes) {
+        throw transportFailure(phase);
+    }
+}
+function requireSuccess(status, phase) {
+    if (status >= 200 && status < 300)
+        return;
+    if (phase === "measure_ip" || phase === "generate_payload") {
+        // Hyper's own service: a rejected key is a credential fault, anything else is transport.
+        throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, status === 401 || status === 403 ? "missing_credentials" : "transport_failure", { phase });
+    }
+    // The upstream refused the script GET or the payload POST: that is the challenge verdict.
+    throw new ResolverChallengeVerdictError(HYPERSOLUTIONS_VENDOR_ID, "solve_failed", { phase });
+}
+function parseObservedIp(body) {
+    let value = body.trim();
+    try {
+        value = JSON.parse(body);
+    }
+    catch {
+        // Hyper's reflector has returned both JSON and plain text in measured clients.
+    }
+    if (value && typeof value === "object" && !Array.isArray(value) && "ip" in value) {
+        value = value.ip;
+    }
+    if (typeof value !== "string")
+        return undefined;
+    const candidate = value.trim();
+    return isIP(candidate) ? candidate : undefined;
+}
+function parsePayload(body) {
+    try {
+        const parsed = JSON.parse(body);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || !("payload" in parsed)) {
+            return undefined;
+        }
+        return typeof parsed.payload === "string" && parsed.payload.length > 0
+            ? parsed.payload
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function scriptExchangeUrls(scriptUrl, laterChallengeToken) {
+    // `?v=&t=` is the hard SBSD variant and `?v=` is passive SBSD. A no-query
+    // Akamai script is a sensor-family artifact and stays outside this adapter.
+    const parsed = new URL(scriptUrl);
+    const uuid = parsed.searchParams.get("v")?.trim();
+    if (!uuid) {
+        throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "missing_challenge_input", {
+            missingFields: ["scriptUrl"],
+            phase: "fetch_script",
+        });
+    }
+    const scriptToken = parsed.searchParams.get("t")?.trim();
+    const laterToken = laterChallengeToken?.trim();
+    if (scriptToken && laterToken) {
+        throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "missing_challenge_input", {
+            missingFields: ["challengeToken"],
+            phase: "fetch_script",
+        });
+    }
+    // Clone the validated URL and only replace its query: reparsing `pathname`
+    // against `origin` would read a `//host/...` pathname as a network-path
+    // reference and swap the host that assertChallengeInput just admitted.
+    const fetchUrl = new URL(parsed);
+    fetchUrl.search = "";
+    fetchUrl.hash = "";
+    fetchUrl.searchParams.set("v", uuid);
+    if (scriptToken)
+        fetchUrl.searchParams.set("t", scriptToken);
+    const postUrl = new URL(fetchUrl);
+    postUrl.search = "";
+    const postToken = laterToken || scriptToken;
+    if (postToken)
+        postUrl.searchParams.set("t", postToken);
+    return {
+        fetchUrl: fetchUrl.toString(),
+        postUrl: postUrl.toString(),
+        uuid,
+        indices: postToken ? [0] : [0, 1],
+    };
+}
+function assertChallengeInput(challenge, allowedHosts) {
+    const missingFields = [
+        ...(challenge.pageUrl.trim() ? [] : ["pageUrl"]),
+        ...(challenge.scriptUrl.trim() ? [] : ["scriptUrl"]),
+        ...(challenge.stateCookieName === "sbsd_o" || challenge.stateCookieName === "bm_so"
+            ? []
+            : ["stateCookieName"]),
+        ...(challenge.challengeToken === undefined || challenge.challengeToken.trim()
+            ? []
+            : ["challengeToken"]),
+    ];
+    if (missingFields.length > 0) {
+        throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "missing_challenge_input", {
+            missingFields,
+        });
+    }
+    assertResolverHostAllowed(challenge.pageUrl, allowedHosts);
+    assertResolverHostAllowed(challenge.scriptUrl, allowedHosts);
+    if (new URL(challenge.pageUrl).origin !== new URL(challenge.scriptUrl).origin) {
+        // The state cookie is read for pageUrl and posted to scriptUrl; they must share an origin.
+        throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "missing_challenge_input", {
+            missingFields: ["scriptUrl"],
+        });
+    }
+}
+async function boundFetch(transport, url, init, phase) {
+    try {
+        return await transport.fetch(url, init);
+    }
+    catch (cause) {
+        if (cause instanceof ResolverVendorUnavailableError ||
+            cause instanceof ResolverChallengeVerdictError) {
+            throw cause;
+        }
+        // An abort is the caller's (or the adapter timeout's) verdict, not a transport fault.
+        if (init.signal.aborted)
+            throw init.signal.reason ?? cause;
+        throw transportFailure(phase, cause);
+    }
+}
+async function readBoundedText(response, maxBytes) {
+    if (declaredLengthExceeds(response.headers.get("content-length")?.trim(), maxBytes)) {
+        await response.body?.cancel();
+        return undefined;
+    }
+    if (!response.body)
+        return "";
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let received = 0;
+    let text = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        received += value.byteLength;
+        if (received > maxBytes) {
+            await reader.cancel();
+            return undefined;
+        }
+        text += decoder.decode(value, { stream: true });
+    }
+    return text + decoder.decode();
+}
+async function generatePayload(fetchImpl, apiKey, body, signal) {
+    try {
+        const response = await fetchImpl(HYPER_SBSD_URL, {
+            method: "POST",
+            headers: {
+                accept: "application/json",
+                "content-type": "application/json",
+                "x-api-key": apiKey,
+            },
+            body,
+            signal,
+            redirect: "error",
+        });
+        // A body that fails mid-read is as much a transport fault as a refused connection.
+        return { status: response.status, body: await readBoundedText(response, BODY_MAX_BYTES) };
+    }
+    catch (cause) {
+        if (signal.aborted)
+            throw signal.reason ?? cause;
+        throw transportFailure("generate_payload", cause);
+    }
+}
+export function createHypersolutionsResolverVendorAdapter(options) {
+    const apiKey = options.apiKey?.trim();
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    return {
+        id: HYPERSOLUTIONS_VENDOR_ID,
+        requiresTransport: true,
+        transportAllowedHosts: HYPER_TRANSPORT_HOSTS,
+        supports: (kind) => kind === "akamai_sbsd",
+        async solve(challenge, _identity, signal, traceRecorder, transport, usage) {
+            const timeoutController = new AbortController();
+            const operationSignal = options.timeoutMs
+                ? AbortSignal.any([signal, timeoutController.signal])
+                : signal;
+            const timeout = options.timeoutMs
+                ? setTimeout(
+                // A named reason lets the usage span record `timeout`, not a caller abort.
+                () => timeoutController.abort(new DOMException("Hyper solve timed out", "TimeoutError")), options.timeoutMs)
+                : undefined;
+            const runPhase = (phase, fn) => traceRecorder ? traceRecorder.runSpan(`resolver.vendor.${phase}`, fn) : fn();
+            try {
+                if (challenge.kind !== "akamai_sbsd") {
+                    throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "not_implemented");
+                }
+                if (!apiKey) {
+                    throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "missing_credentials");
+                }
+                if (!transport?.getCookie) {
+                    throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "missing_transport");
+                }
+                const sessionHeaders = transport.sessionHeaders;
+                const userAgent = sessionHeaders ? headerValue(sessionHeaders, "user-agent") : undefined;
+                const acceptLanguage = sessionHeaders
+                    ? headerValue(sessionHeaders, "accept-language")
+                    : undefined;
+                if (!sessionHeaders || !userAgent || !acceptLanguage) {
+                    throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "missing_client_profile");
+                }
+                assertChallengeInput(challenge, options.allowedHosts);
+                const exchange = scriptExchangeUrls(challenge.scriptUrl, challenge.challengeToken);
+                // Hyper documents /ip as an authenticated service request but does not
+                // publish an explicit exclusion from request quota. Meter conservatively.
+                const ip = await recordPaidResolverCreate({
+                    traceRecorder,
+                    vendor: HYPERSOLUTIONS_VENDOR_ID,
+                    kind: challenge.kind,
+                    endpoint: "hyper:ip",
+                    signal: operationSignal,
+                    usage,
+                    create: () => runPhase("measure_ip", async () => {
+                        const ipResponse = await boundFetch(transport, HYPER_IP_URL, {
+                            method: "GET",
+                            headers: {
+                                accept: "application/json, text/plain;q=0.9",
+                                "x-api-key": apiKey,
+                            },
+                            signal: operationSignal,
+                            redirect: "manual",
+                            maxBodyBytes: IP_RESPONSE_MAX_BYTES,
+                        }, "measure_ip");
+                        requireSuccess(ipResponse.status, "measure_ip");
+                        assertBoundedBody(ipResponse, IP_RESPONSE_MAX_BYTES, "measure_ip");
+                        const observedIp = parseObservedIp(ipResponse.body);
+                        if (!observedIp)
+                            throw transportFailure("measure_ip");
+                        return observedIp;
+                    }),
+                });
+                const scriptResponse = await runPhase("fetch_script", async () => {
+                    const scriptResponse = await boundFetch(transport, exchange.fetchUrl, {
+                        method: "GET",
+                        headers: { ...sessionHeaders, Referer: challenge.pageUrl },
+                        signal: operationSignal,
+                        redirect: "manual",
+                        maxBodyBytes: BODY_MAX_BYTES,
+                    }, "fetch_script");
+                    requireSuccess(scriptResponse.status, "fetch_script");
+                    assertBoundedBody(scriptResponse, BODY_MAX_BYTES, "fetch_script");
+                    if (!scriptResponse.body) {
+                        throw new ResolverChallengeVerdictError(HYPERSOLUTIONS_VENDOR_ID, "solve_failed", {
+                            phase: "fetch_script",
+                        });
+                    }
+                    return scriptResponse;
+                });
+                const stateCookie = transport
+                    .getCookie(challenge.stateCookieName, challenge.pageUrl)
+                    ?.trim();
+                if (!stateCookie) {
+                    throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "missing_challenge_input", { missingFields: [challenge.stateCookieName], phase: "fetch_script" });
+                }
+                let expires;
+                for (const [roundIndex, index] of exchange.indices.entries()) {
+                    const round = roundIndex + 1;
+                    const payload = await recordPaidResolverCreate({
+                        traceRecorder,
+                        vendor: HYPERSOLUTIONS_VENDOR_ID,
+                        kind: challenge.kind,
+                        endpoint: "hyper:sbsd_create",
+                        round,
+                        signal: operationSignal,
+                        usage,
+                        create: () => runPhase("generate_payload", async () => {
+                            const hyperResponse = await generatePayload(fetchImpl, apiKey, JSON.stringify({
+                                index,
+                                uuid: exchange.uuid,
+                                o: stateCookie,
+                                pageUrl: challenge.pageUrl,
+                                userAgent,
+                                script: scriptResponse.body,
+                                ip,
+                                acceptLanguage,
+                            }), operationSignal);
+                            requireSuccess(hyperResponse.status, "generate_payload");
+                            const generated = hyperResponse.body === undefined ? undefined : parsePayload(hyperResponse.body);
+                            if (!generated) {
+                                throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "transport_failure", { phase: "generate_payload", round });
+                            }
+                            return generated;
+                        }),
+                    });
+                    const postResponse = await runPhase("post_payload", async () => {
+                        const postResponse = await boundFetch(transport, exchange.postUrl, {
+                            method: "POST",
+                            headers: {
+                                ...sessionHeaders,
+                                "content-type": "application/json",
+                                Referer: challenge.pageUrl,
+                            },
+                            body: JSON.stringify({ body: payload }),
+                            signal: operationSignal,
+                            redirect: "manual",
+                            maxBodyBytes: BODY_MAX_BYTES,
+                        }, "post_payload");
+                        requireSuccess(postResponse.status, "post_payload");
+                        assertBoundedBody(postResponse, BODY_MAX_BYTES, "post_payload");
+                        return postResponse;
+                    });
+                    expires =
+                        postResponse.cookies.find((cookie) => cookie.name === challenge.stateCookieName)
+                            ?.expires ?? expires;
+                }
+                // A 2xx payload POST is not proof of a solve and the state cookie is not
+                // required to rotate (measured zozotown source and Hyper's docs both verify
+                // only through the next protected GET, which is Phase 2).
+                return {
+                    form: "cookie_state",
+                    kind: "akamai_sbsd",
+                    outcome: "payload_accepted",
+                    verified: false,
+                    stateCookieName: challenge.stateCookieName,
+                    ...(expires === undefined ? {} : { expires }),
+                };
+            }
+            catch (error) {
+                if (timeoutController.signal.aborted && !signal.aborted) {
+                    throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "timeout");
+                }
+                throw error;
+            }
+            finally {
+                if (timeout !== undefined)
+                    clearTimeout(timeout);
+            }
+        },
+    };
+}

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

@@ -1,6 +1,6 @@
 import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
 import type { TraceRecorder } from "../trace.js";
-import { type ResolverIdentity, type ResolverVendorAdapter } from "./types.js";
+import { type ResolverIdentity, type ResolverPaidUsageContext, type ResolverVendorAdapter, type ResolverVendorTransport } from "./types.js";
 type Delay = (ms: number, signal: AbortSignal) => Promise<void>;
 export interface TwoCaptchaResolverVendorOptions {
     readonly apiKey?: string;
@@ -16,7 +16,7 @@ export interface TwoCaptchaResolverVendorOptions {
 }
 export interface TwoCaptchaResolverVendorAdapter extends ResolverVendorAdapter {
     readonly id: "2captcha";
-    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder): Promise<Extract<ChallengeSolution, {
+    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder, transport?: ResolverVendorTransport, usage?: ResolverPaidUsageContext): Promise<Extract<ChallengeSolution, {
         readonly form: "token";
     }>>;
 }

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

@@ -1,5 +1,6 @@
+import { recordPaidResolverCreate } from "../resolver-usage.js";
 import { assertResolverHostAllowed } from "./hosts.js";
-import { ResolverChallengeVerdictError, ResolverVendorUnavailableError, resolverVendorSupports, } from "./types.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;
@@ -225,7 +226,7 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
         supports(kind) {
             return resolverVendorSupports(TWOCAPTCHA_VENDOR_ID, kind);
         },
-        async solve(challenge, identity, callerSignal, traceRecorder) {
+        async solve(challenge, identity, callerSignal, traceRecorder, _transport, usage) {
             const apiKey = options.apiKey?.trim();
             if (!apiKey) {
                 throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "missing_credentials", {
@@ -325,12 +326,22 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
                                             (() => {
                                                 throw new TypeError(`2captcha resolver does not support ${challenge.kind}`);
                                             })();
-                    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;
+                    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, {
@@ -352,6 +363,7 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
                         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);
@@ -359,11 +371,15 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
                         if (pollResult.payload.status === "processing")
                             continue;
                         if (pollResult.payload.status !== "ready") {
-                            throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", { phase });
+                            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 });
+                            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 };

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

@@ -1,18 +1,22 @@
 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 custom: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "cloudflare_interstitial", "aws_waf", "akamai_sec_cpt", "akamai_sensor"];
+    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"];
+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[];
@@ -27,9 +31,19 @@ export interface ResolverIssuingIdentity {
 }
 export interface ResolverVendorTransport {
     /**
-     * Bound to the resolved proxy lease and client profile.
-     * Implementations MUST NOT follow redirects and MUST return the initial redirect response.
+     * 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>>;
@@ -37,6 +51,8 @@ export interface ResolverVendorTransport {
         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>>;
@@ -55,13 +71,27 @@ export interface ResolverVendorTransport {
         }[];
     }>;
 }
+/** 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.
+     * Honored for every adapter the chain runs, so whoever supplies `adapters` to
+     * `createResolverClient` is the trust boundary; the engine path
+     * (`createResolverClientFromEnv`) only constructs registry adapters.
+     */
+    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): Promise<ChallengeSolution>;
+    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";