@apifuse/provider-sdk 2.2.0-beta.25 → 2.2.0-beta.26

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

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

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

@@ -0,0 +1,264 @@
+import { assertResolverHostAllowed } from "./hosts.js";
+import { 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 raceWithAbort(operation, signal, phase) {
+    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", {
+                cause: error,
+                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 unavailableForPayload(payload, phase) {
+    return new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, isAllocationExhausted(payload) ? "allocation_exhausted" : "transport_failure", { phase });
+}
+async function postJson(fetchImpl, url, body, signal, phase) {
+    const response = await raceWithAbort(() => fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        signal,
+        redirect: "error",
+    }), signal, phase);
+    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) {
+    const solution = payload.solution;
+    if (!isJsonRecord(solution))
+        return 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}`;
+}
+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) {
+            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") {
+                // AWS WAF remains deferred because its challenge variant has no required site key.
+                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 createResult = await postJson(fetchImpl, endpoint(baseUrl, "createTask"), {
+                    clientKey: apiKey,
+                    task: {
+                        type: proxy ? "RecaptchaV2Task" : "RecaptchaV2TaskProxyless",
+                        websiteURL: challenge.pageUrl,
+                        websiteKey: challenge.siteKey,
+                        isInvisible: false,
+                        ...(identity ? { userAgent: identity.userAgent } : {}),
+                        ...(proxy ?? {}),
+                    },
+                }, solveController.signal, phase);
+                const taskId = taskIdFrom(createResult.payload);
+                if (!createResult.ok || createResult.payload.errorId !== 0 || taskId === undefined) {
+                    throw unavailableForPayload(createResult.payload, phase);
+                }
+                phase = "poll_result";
+                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);
+                    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);
+                    if (!token?.trim()) {
+                        throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
+                            phase,
+                        });
+                    }
+                    return { form: "token", token };
+                }
+            }
+            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)
+                    throw error;
+                throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
+                    cause: error,
+                    phase,
+                });
+            }
+            finally {
+                if (timeout !== undefined)
+                    clearTimeout(timeout);
+                callerSignal.removeEventListener("abort", onCallerAbort);
+            }
+        },
+    };
+}

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

@@ -2,10 +2,10 @@ import type { ChallengeSolution, ProviderChallenge, ProviderChallengeKind, Provi
 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"];
+    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"];
+    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 {
@@ -17,21 +17,62 @@ export interface ResolverIssuingIdentity {
     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): Promise<ChallengeSolution>;
+    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder, transport?: ResolverVendorTransport): Promise<ChallengeSolution>;
 }
 export type ResolverVendorUnavailableReason = "missing_credentials" | "missing_transport" | "allocation_exhausted" | "transport_failure" | "timeout" | "not_implemented";
 export type ResolverChallengeVerdictReason = "human_puzzle";
 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 {

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

@@ -7,6 +7,8 @@ export const RESOLVER_VENDOR_CAPABILITIES = {
         "hcaptcha",
         "cloudflare_interstitial",
         "aws_waf",
+        "akamai_sec_cpt",
+        "akamai_sensor",
     ],
     capsolver: [
         "turnstile",
@@ -24,6 +26,8 @@ export const RESOLVER_VENDOR_CAPABILITIES = {
         "hcaptcha",
         "cloudflare_interstitial",
         "aws_waf",
+        "akamai_sec_cpt",
+        "akamai_sensor",
     ],
 };
 export function resolverVendorSupports(vendor, kind) {
@@ -32,6 +36,9 @@ export function resolverVendorSupports(vendor, 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;
@@ -40,6 +47,9 @@ export class ResolverVendorUnavailableError extends Error {
         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 {

package/dist/runtime/resolver.d.ts

@@ -1,5 +1,5 @@
 import type { ChallengeSolution, ProviderCache, ProviderChallenge, ProviderChallengeKind, ProviderResolverConfig, ProviderResolverVendor, ResolverContext } from "../types.js";
-import { type ResolverIdentity, type ResolverVendorAdapter } from "./resolver-vendors/types.js";
+import { type ResolverIdentity, type ResolverVendorAdapter, type ResolverVendorTransport } from "./resolver-vendors/types.js";
 import type { TraceRecorder } from "./trace.js";
 export declare const APIFUSE__RESOLVER__2CAPTCHA__API_KEY = "APIFUSE__RESOLVER__2CAPTCHA__API_KEY";
 export declare const APIFUSE__RESOLVER__CAPSOLVER__API_KEY = "APIFUSE__RESOLVER__CAPSOLVER__API_KEY";
@@ -16,14 +16,23 @@ export interface ResolverRuntimeOptions {
     readonly cache?: ProviderCache;
     /** 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 declare const RESOLVER_INSTRUMENTATION_METADATA: unique symbol;
 export type ResolverInstrumentationMetadata = {
     readonly target: ResolverContext;
     readonly traceRecorder: TraceRecorder;
 };
-type ResolverAdapterFactory = (configuration: string, timeoutMs: number, allowedHosts: readonly string[]) => ResolverVendorAdapter;
+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;
 /** 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: {
@@ -32,8 +41,14 @@ export declare function createResolverClient(options: {
     readonly unavailableReason?: string;
     readonly cache?: ProviderCache;
     readonly identity?: ResolverIdentity;
+    readonly transport?: ResolverVendorTransport;
+    readonly createTransport?: ResolverRuntimeOptions["createTransport"];
+    readonly clientProfile?: string;
+    readonly allowedHosts?: readonly string[];
 }): ResolverChainClient;
 export declare function createUnsupportedResolverClient(reason?: string): ResolverContext;
 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;
 export {};