@apifuse/provider-sdk 2.2.0-beta.36 → 2.2.0-beta.37

package/dist/runtime/browser.js

@@ -548,8 +548,8 @@ class PlaywrightBrowserPage {
         this.page = page;
         this.proxy = proxy;
     }
-    async goto(url) {
-        await this.page.goto(url);
+    async goto(url, options) {
+        await this.page.goto(url, options);
     }
     async evaluate(fn) {
         if (typeof fn === "string") {
@@ -1101,16 +1101,22 @@ class CdpPoolBrowserPage {
     get id() {
         return this.pageId;
     }
-    async goto(url) {
+    async goto(url, options) {
         await this.initialize();
         const startedAt = Date.now();
-        let loadEventSeen = false;
-        const unsubscribe = this.pageClient.on("Page.loadEventFired", () => {
-            loadEventSeen = true;
+        const timeout = options?.timeout ?? DEFAULT_WAIT_TIMEOUT_MS;
+        const waitUntil = options?.waitUntil ?? "load";
+        let expectedEventSeen = false;
+        const eventName = waitUntil === "domcontentloaded" ? "Page.domContentEventFired" : "Page.loadEventFired";
+        const unsubscribe = this.pageClient.on(eventName, () => {
+            expectedEventSeen = true;
         });
         try {
-            await this.pageClient.send("Page.navigate", { url });
-            await this.waitForDocumentReady(startedAt + DEFAULT_WAIT_TIMEOUT_MS, () => loadEventSeen);
+            const navigation = (await this.pageClient.send("Page.navigate", { url }));
+            if (typeof navigation.errorText === "string" && navigation.errorText.length > 0) {
+                throw new Error(`Page.navigate failed: ${navigation.errorText} at ${url}`);
+            }
+            await this.waitForDocumentReady(startedAt + timeout, () => expectedEventSeen, waitUntil);
         }
         finally {
             unsubscribe();
@@ -1397,11 +1403,13 @@ class CdpPoolBrowserPage {
         this.frameExecutionContexts.set(frameId, contextId);
         return contextId;
     }
-    async waitForDocumentReady(deadline, isLoadEventSeen) {
+    async waitForDocumentReady(deadline, isExpectedEventSeen, waitUntil) {
         while (Date.now() < deadline) {
             const readyState = await this.evaluate("document.readyState");
-            if (readyState === "complete" || readyState === "interactive") {
-                if (isLoadEventSeen() || readyState === "complete") {
+            const documentReady = readyState === "complete" ||
+                (waitUntil === "domcontentloaded" && readyState === "interactive");
+            if (documentReady) {
+                if (isExpectedEventSeen() || readyState === "complete") {
                     return;
                 }
             }

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

@@ -1 +1 @@
-export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_TIMEOUT_MS, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, type ResolverAdapterFactory, type ResolverInstrumentationMetadata, type ResolverRuntimeOptions, } from "./resolver.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, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, type ResolverAdapterFactory, type ResolverInstrumentationMetadata, type ResolverRuntimeOptions, } from "./resolver.js";

package/dist/runtime/resolver-public.js

@@ -1 +1 @@
-export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_TIMEOUT_MS, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver.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, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, } from "./resolver.js";

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

@@ -5,6 +5,7 @@ import { assertResolverHostAllowed, normalizedResolverHostname } from "./hosts.j
 import { ResolverVendorUnavailableError, } from "./types.js";
 const BROWSER_VENDOR_ID = "browser";
 const DEFAULT_COOKIE_POLL_INTERVAL_MS = 100;
+const NAVIGATION_BLOCKED_ERROR_TEXT = "net::ERR_BLOCKED_BY_CLIENT";
 const AWS_WAF_CHALLENGE_INFRASTRUCTURE_HOST_SUFFIX = ".awswaf.com";
 const RESOLVER_DOCUMENT_CONTENT_SECURITY_POLICY = "connect-src http: https:; worker-src 'none'";
 const SUCCESS_COOKIE_NAMES = {
@@ -25,11 +26,32 @@ export function swapBrowserResolverClientFactoryForTests(factory) {
     };
 }
 class BrowserSolveTimeoutError extends Error {
-    constructor() {
-        super("Browser resolver solve budget elapsed");
+    constructor(blockedRequests) {
+        super(`Browser resolver solve budget elapsed${formatBlockedRequests(blockedRequests)}`);
         this.name = "BrowserSolveTimeoutError";
     }
 }
+class BrowserNavigationBlockedError extends Error {
+    navigationUrl;
+    blockedUrls;
+    code = "RESOLVER_BROWSER_NAVIGATION_BLOCKED";
+    constructor(navigationUrl, blockedUrls, options) {
+        super(`Browser resolver navigation was blocked for ${navigationUrl}${formatBlockedRequests(blockedUrls)}`, options);
+        this.navigationUrl = navigationUrl;
+        this.blockedUrls = blockedUrls;
+        this.name = "BrowserNavigationBlockedError";
+    }
+}
+function formatBlockedRequests(blockedRequests) {
+    if (blockedRequests.length === 0)
+        return "";
+    const displayed = blockedRequests.slice(0, 5);
+    const remainder = blockedRequests.length - displayed.length;
+    return `; blocked ${blockedRequests.length} requests: [${displayed.join(", ")}]${remainder > 0 ? ` (+${remainder} more)` : ""}`;
+}
+function isNavigationBlockedError(error) {
+    return error instanceof Error && error.message.includes(NAVIGATION_BLOCKED_ERROR_TEXT);
+}
 class BrowserCleanupTimeoutError extends Error {
     constructor(timeoutMs) {
         super(`Browser resolver cleanup exceeded ${timeoutMs}ms`);
@@ -141,23 +163,35 @@ function selectSuccessCookie(cookies, successCookieName, pageUrl) {
         cookieDomainSpecificity(right) - cookieDomainSpecificity(left) ||
         right.path.length - left.path.length)[0];
 }
-async function solveInPage(page, challengeKind, pageUrl, allowedHosts, successCookieName, pollIntervalMs, signal) {
+async function solveInPage(page, challengeKind, pageUrl, allowedHosts, successCookieName, pollIntervalMs, gotoTimeoutMs, blockedRequests, signal) {
     return await page.withResourcePolicy({
         allowedMethods: ["GET", "HEAD", "POST"],
         documentContentSecurityPolicy: RESOLVER_DOCUMENT_CONTENT_SECURITY_POLICY,
         routes: [
             {
                 match: () => true,
-                handle: (request) => ({
-                    action: isResolverBrowserRequestAllowed(request.url, challengeKind, allowedHosts)
-                        ? "continue"
-                        : "block",
-                }),
+                handle: (request) => {
+                    if (isResolverBrowserRequestAllowed(request.url, challengeKind, allowedHosts)) {
+                        return { action: "continue" };
+                    }
+                    blockedRequests.add(request.url);
+                    return { action: "block" };
+                },
             },
         ],
     }, async () => {
         const userAgent = await raceWithAbort(() => page.userAgent(), signal);
-        await raceWithAbort(() => page.goto(pageUrl), signal);
+        try {
+            await raceWithAbort(() => page.goto(pageUrl, {
+                timeout: gotoTimeoutMs,
+                waitUntil: "domcontentloaded",
+            }), signal);
+        }
+        catch (error) {
+            if (!isNavigationBlockedError(error))
+                throw error;
+            throw new BrowserNavigationBlockedError(pageUrl, [...blockedRequests], { cause: error });
+        }
         while (true) {
             const cookies = await raceWithAbort(() => page.cookies(), signal);
             const successCookie = selectSuccessCookie(cookies, successCookieName, pageUrl);
@@ -203,7 +237,7 @@ function poolErrorCode(error) {
     const code = error.code;
     return typeof code === "number" ? code : undefined;
 }
-function knownUnavailableReason(error) {
+function knownUnavailableReason(error, beforePageSolve = false) {
     // Source-grounded mappings:
     // - apps/cdp-pool/src/index.ts: the JSON-RPC codes and messages below.
     // - src/runtime/browser.ts: BROWSER_CDP_POOL_REQUIRED and the two WebSocket messages.
@@ -230,7 +264,10 @@ function knownUnavailableReason(error) {
         error.message.includes("WebSocket closed")) {
         return "transport_failure";
     }
-    return undefined;
+    // Browser creation, Playwright launch, and CDP connection all happen before the
+    // isolated-page handler is entered. Errors after that boundary belong to the
+    // challenge solve and must retain their existing classification.
+    return beforePageSolve ? "transport_failure" : undefined;
 }
 async function closeBrowserClient(client, timeoutMs, challengeKind, traceRecorder) {
     const close = client?.close;
@@ -274,10 +311,11 @@ export function createBrowserResolverVendorAdapter(options) {
                 // Refuse so the chain can choose a vendor that can honor the resolved identity.
                 throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, "not_implemented");
             }
+            const blockedRequests = new Set();
             const solveController = new AbortController();
             const onCallerAbort = () => solveController.abort(abortReason(callerSignal));
             callerSignal.addEventListener("abort", onCallerAbort, { once: true });
-            const timeout = setTimeout(() => solveController.abort(new BrowserSolveTimeoutError()), options.timeoutMs);
+            const timeout = setTimeout(() => solveController.abort(new BrowserSolveTimeoutError([...blockedRequests])), options.timeoutMs);
             let client;
             let handlerEntered = false;
             try {
@@ -290,7 +328,7 @@ export function createBrowserResolverVendorAdapter(options) {
                 });
                 const contextOperation = client.withIsolatedContext(async (page) => {
                     handlerEntered = true;
-                    return await solveInPage(page, challengeKind, challenge.pageUrl, options.allowedHosts, SUCCESS_COOKIE_NAMES[challengeKind], pollIntervalMs, solveController.signal);
+                    return await solveInPage(page, challengeKind, challenge.pageUrl, options.allowedHosts, SUCCESS_COOKIE_NAMES[challengeKind], pollIntervalMs, options.timeoutMs, blockedRequests, solveController.signal);
                 });
                 try {
                     return await raceWithAbort(() => contextOperation, solveController.signal);
@@ -315,10 +353,15 @@ export function createBrowserResolverVendorAdapter(options) {
                         cause: error,
                     });
                 }
+                if (error instanceof BrowserNavigationBlockedError) {
+                    throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, "transport_failure", {
+                        cause: error,
+                    });
+                }
                 if (error instanceof ResolverVendorUnavailableError) {
                     throw error;
                 }
-                const reason = knownUnavailableReason(error);
+                const reason = knownUnavailableReason(error, !handlerEntered);
                 if (reason) {
                     throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, reason, { cause: error });
                 }

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

@@ -1,4 +1,4 @@
-import type { ChallengeSolution, ProviderChallenge, ProviderChallengeKind, ProviderResolverVendor } from "../../types.js";
+import type { ChallengeSolution, ProviderChallenge, ProviderChallengeKind, ProviderResolverConfig, ProviderResolverVendor } from "../../types.js";
 import type { TraceRecorder } from "../trace.js";
 export declare const RESOLVER_VENDOR_CAPABILITIES: {
     readonly browser: readonly ["aws_waf", "cloudflare_interstitial"];
@@ -7,7 +7,15 @@ export declare const RESOLVER_VENDOR_CAPABILITIES: {
     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"];
 };
+/**
+ * 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 function resolverVendorSupports(vendor: ProviderResolverVendor, kind: ProviderChallengeKind): boolean;
+/** Resolves an explicit provider override or the SDK-owned default vendor chain. */
+export declare function resolveProviderResolverVendors(config: ProviderResolverConfig): readonly ProviderResolverVendor[];
 export interface ResolverIdentity {
     readonly proxyUrl: string;
     readonly userAgent: string;

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

@@ -33,9 +33,24 @@ export const RESOLVER_VENDOR_CAPABILITIES = {
         "akamai_sensor",
     ],
 };
+/**
+ * SDK-owned fallback policy for hosted resolver vendors. Capability support is
+ * applied separately, so each provider receives only vendors that support one
+ * or more of its declared challenge kinds.
+ */
+export const DEFAULT_RESOLVER_VENDOR_PREFERENCE = [
+    "capsolver",
+    "2captcha",
+];
 export function resolverVendorSupports(vendor, kind) {
     return RESOLVER_VENDOR_CAPABILITIES[vendor].includes(kind);
 }
+/** Resolves an explicit provider override or the SDK-owned default vendor chain. */
+export function resolveProviderResolverVendors(config) {
+    if (config.vendors !== undefined)
+        return config.vendors;
+    return DEFAULT_RESOLVER_VENDOR_PREFERENCE.filter((vendor) => config.kinds.some((kind) => resolverVendorSupports(vendor, kind)));
+}
 export class ResolverVendorUnavailableError extends Error {
     vendor;
     reason;

package/dist/runtime/resolver.d.ts

@@ -4,6 +4,7 @@ import { type ResolverIdentity, type ResolverVendorAdapter, type ResolverVendorT
 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";
+export { DEFAULT_RESOLVER_VENDOR_PREFERENCE, resolveProviderResolverVendors, } from "./resolver-vendors/types.js";
 type EnvLike = Record<string, string | undefined>;
 type ResolverChainClient = ResolverContext & {
     solve(challenge: ProviderChallenge, signal?: AbortSignal, traceRecorder?: TraceRecorder): Promise<ChallengeSolution>;

package/dist/runtime/resolver.js

@@ -7,12 +7,13 @@ import { createBrowserResolverVendorAdapter } from "./resolver-vendors/browser.j
 import { createCapsolverResolverVendorAdapter } from "./resolver-vendors/capsolver.js";
 import { assertResolverHostAllowed } from "./resolver-vendors/hosts.js";
 import { createTwoCaptchaResolverVendorAdapter } from "./resolver-vendors/twocaptcha.js";
-import { RESOLVER_VENDOR_CAPABILITIES, ResolverVendorUnavailableError, resolverVendorSupports, } from "./resolver-vendors/types.js";
+import { RESOLVER_VENDOR_CAPABILITIES, ResolverVendorUnavailableError, resolveProviderResolverVendors, resolverVendorSupports, } from "./resolver-vendors/types.js";
 import { createUnsupportedResolverClient, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver-shared.js";
 import { 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";
 import { DEFAULT_PROFILE } from "./stealth.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";
+export { DEFAULT_RESOLVER_VENDOR_PREFERENCE, resolveProviderResolverVendors, } from "./resolver-vendors/types.js";
 const RESOLVER_SOLUTION_CACHE_NAMESPACE = "resolver-solution";
 const RESOLVER_SOLUTION_INDEX_CACHE_NAMESPACE = "resolver-solution-index";
 const MIN_RESOLVER_CACHE_TTL_MS = 1_000;
@@ -169,10 +170,12 @@ function assertKnownResolverVendor(vendor) {
         return;
     throw new Error(`Unknown resolver vendor "${vendor}" in resolver configuration`);
 }
-function throwUnsupportedKind(kind) {
+function throwUnsupportedKind(kind, usingDefaultVendors) {
     throw new ProviderError(`Resolver vendor chain does not support kind "${kind}"`, {
         code: "RESOLVER_KIND_UNSUPPORTED_BY_CHAIN",
-        fix: `Add a resolver vendor that supports "${kind}" to the provider's resolver.vendors declaration.`,
+        fix: usingDefaultVendors
+            ? `No SDK default resolver vendor supports "${kind}". Declare an explicit resolver.vendors override with a supporting vendor.`
+            : `Add a resolver vendor that supports "${kind}" to the provider's resolver.vendors declaration.`,
     });
 }
 function throwExhausted(attempts) {
@@ -542,8 +545,9 @@ function createResolverChainClient(options) {
                 });
             }
             const supportingEntries = options.entries.filter((entry) => entry.supports(challenge.kind));
-            if (supportingEntries.length === 0)
-                throwUnsupportedKind(challenge.kind);
+            if (supportingEntries.length === 0) {
+                throwUnsupportedKind(challenge.kind, options.usingDefaultVendors ?? false);
+            }
             signal.throwIfAborted();
             const identityResolution = options.proxyIntent
                 ? await resolveResolverIdentity(options.proxyIntent)
@@ -692,7 +696,8 @@ function createResolverClientFromEnvInternal(config, env, options, adapterFactor
         return createUnsupportedResolverClient("Provider does not declare resolver capability");
     }
     assertClientProfileTransportContract(config.clientProfile, options.transport);
-    if (config.vendors.length === 0) {
+    const vendors = resolveProviderResolverVendors(config);
+    if (config.vendors !== undefined && config.vendors.length === 0) {
         return createResolverChainClient({
             kinds: config.kinds,
             entries: [],
@@ -704,7 +709,7 @@ function createResolverClientFromEnvInternal(config, env, options, adapterFactor
     const allowedHosts = [...(options.allowedHosts ?? [])];
     return createResolverChainClient({
         kinds: config.kinds,
-        entries: config.vendors.map((configuredVendor) => {
+        entries: vendors.map((configuredVendor) => {
             assertKnownResolverVendor(configuredVendor);
             const vendor = configuredVendor;
             return {
@@ -713,6 +718,7 @@ function createResolverClientFromEnvInternal(config, env, options, adapterFactor
                 createAdapter: () => createAdapter(resolveVendorAvailability(vendor, env), timeoutMs, allowedHosts, adapterFactories),
             };
         }),
+        usingDefaultVendors: config.vendors === undefined,
         cache: options.cache,
         proxyIntent: options.proxyIntent,
         identityScope: options.identityScope,

package/dist/server/serve-implementation.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join } from "node:path";
@@ -924,6 +925,28 @@ function extractRequestId(raw) {
     const value = Object.getOwnPropertyDescriptor(raw, "requestId")?.value;
     return typeof value === "string" ? value : undefined;
 }
+const MAX_PROVIDER_ERROR_CAUSE_FRAMES = 5;
+function providerErrorCauseChain(error) {
+    if (!(error instanceof Error) && !isProviderError(error))
+        return undefined;
+    const seen = new Set([error]);
+    const frames = [];
+    let cause = error.cause;
+    while (frames.length < MAX_PROVIDER_ERROR_CAUSE_FRAMES &&
+        (cause instanceof Error || isProviderError(cause)) &&
+        !seen.has(cause)) {
+        seen.add(cause);
+        const message = cause.message;
+        frames.push({
+            errorClass: cause.name,
+            ...(isProviderError(cause) && typeof cause.code === "string" ? { code: cause.code } : {}),
+            messageLength: message.length,
+            messageFingerprint: createHash("sha256").update(message).digest("hex").slice(0, 12),
+        });
+        cause = cause.cause;
+    }
+    return frames.length > 0 ? frames : undefined;
+}
 function logProviderError(logger, provider, kind, route, requestId, error, status, cost, declaredErrorCode) {
     const code = isProviderError(error)
         ? (error.code ?? "provider_error")
@@ -934,6 +957,7 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
                 : "internal_error";
     const errorClass = error instanceof Error ? error.name : typeof error;
     const message = error instanceof Error ? error.message : String(error);
+    const causeChain = providerErrorCauseChain(error);
     const details = errorObservabilityDetails(error, declaredErrorCode);
     const isUnregisteredProviderErrorCode = status === 500 &&
         isProviderError(error) &&
@@ -954,6 +978,7 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
         code,
         errorClass,
         message,
+        ...(causeChain ? { causeChain } : {}),
         ...(details.upstreamStatus ? { upstreamStatus: details.upstreamStatus } : {}),
         errorCategory: details.category,
         taxonomyVersion: details.taxonomyVersion,

package/dist/types.d.ts

@@ -252,16 +252,16 @@ export interface ProviderSttConfig {
     mode: ProviderSttMode;
 }
 /**
- * `browser` is the in-house CDP pool (`apps/cdp-pool`, reached through
- * `createBrowserClient`) and is a first-class vendor rather than an escape hatch:
- * for fingerprint-family kinds, it was measured faster than a paid vendor
- * (4.5 s vs 17.5 s) at zero marginal cost.
+ * Union order is documentation only.
  *
- * `2captcha` is the vendor already carrying production traffic in
- * `apifuse-provider-tabelog`.
+ * The SDK owns the default hosted-vendor fallback policy and derives the chain
+ * from each provider's declared challenge kinds. Hosted solvers are preferred
+ * with `capsolver` ahead of `2captcha` in that policy.
  *
- * Union order is documentation only; the effective fallback order is whatever
- * `ProviderResolverConfig.vendors` declares.
+ * `browser` is the in-house CDP pool and remains opt-in; it is excluded from the
+ * default chain. `custom` is likewise reserved for provider-specific configuration.
+ *
+ * `ProviderResolverConfig.vendors` overrides the SDK policy when declared.
  */
 export type ProviderResolverVendor = "browser" | "capsolver" | "capmonster" | "2captcha" | "custom";
 /**
@@ -339,8 +339,8 @@ export type ChallengeSolution = {
     readonly expires?: number;
 };
 export interface ProviderResolverConfig {
-    /** Ordered vendor fallback chain, tried first to last. */
-    readonly vendors: readonly ProviderResolverVendor[];
+    /** Optional ordered override for the SDK-owned vendor fallback chain. */
+    readonly vendors?: readonly ProviderResolverVendor[];
     /** Challenge kinds this provider is permitted to request. */
     readonly kinds: readonly ProviderChallengeKind[];
     /**
@@ -1355,8 +1355,6 @@ export interface NativeNetworkClient {
 export interface NativeContext {
     readonly network: NativeNetworkClient;
 }
-/** Consumer-facing alias for the native capability on provider contexts. */
-export type NativeProviderContext = NativeContext;
 export interface NativeProviderConfig {
     readonly network?: {
         readonly tcp?: readonly NativeTcpEgressRule[];
@@ -1496,6 +1494,10 @@ export interface BrowserPage extends BrowserFrame {
     cookies(): Promise<readonly BrowserCookie[]>;
     fill(selector: string, text: string): Promise<void>;
     goto(url: string): Promise<void>;
+    goto(url: string, options?: {
+        readonly timeout?: number;
+        readonly waitUntil?: "load" | "domcontentloaded";
+    }): Promise<void>;
     pageId?: string;
     screenshot(options?: {
         fullPage?: boolean;
@@ -1762,7 +1764,7 @@ export interface FlowContext {
      * un-keyed entries would be shared across all connectionless ceremonies. */
     readonly state?: ProviderRuntimeState;
     /** Present when the selected runtime supplies native network capabilities. */
-    readonly native?: NativeProviderContext;
+    readonly native?: NativeContext;
     stealth: StealthClient;
     env: EnvContext;
     credential?: CredentialContext;
@@ -1863,8 +1865,8 @@ export interface ProviderContext {
     http: HttpClient;
     /** Present for requests carrying runtime-resolvable file references. */
     readonly files?: ProviderFilesContext;
-    /** Present when the selected runtime supplies native network capabilities. */
-    readonly native?: NativeProviderContext;
+    /** Native network capability selected by declaration-derived contexts. */
+    readonly native: NativeContext;
     cache: ProviderCache;
     state: ProviderRuntimeState;
     stealth: StealthClient;
@@ -1876,6 +1878,12 @@ export interface ProviderContext {
     resolver: ResolverContext;
     choice: ProviderChoiceContext;
 }
+/**
+ * The operation context exposed for one provider declaration. Capability
+ * bindings are present only when their corresponding declaration is present;
+ * trace and request remain ambient runtime bindings.
+ */
+export type ProviderContextFor<TConfig> = Pick<ProviderContext, "trace" | "request"> & ("env" extends keyof TConfig ? Pick<ProviderContext, "env"> : Record<never, never>) & ("credential" extends keyof TConfig ? Pick<ProviderContext, "credential"> : Record<never, never>) & ("http" extends keyof TConfig ? Pick<ProviderContext, "http"> : Record<never, never>) & ("files" extends keyof TConfig ? Pick<ProviderContext, "files"> : Record<never, never>) & ("native" extends keyof TConfig ? Pick<ProviderContext, "native"> : Record<never, never>) & ("cache" extends keyof TConfig ? Pick<ProviderContext, "cache"> : Record<never, never>) & ("state" extends keyof TConfig ? Pick<ProviderContext, "state"> : Record<never, never>) & ("stealth" extends keyof TConfig ? Pick<ProviderContext, "stealth"> : Record<never, never>) & ("browser" extends keyof TConfig ? Pick<ProviderContext, "browser"> : Record<never, never>) & ("auth" extends keyof TConfig ? Pick<ProviderContext, "auth"> : Record<never, never>) & ("ocr" extends keyof TConfig ? Pick<ProviderContext, "ocr"> : Record<never, never>) & ("stt" extends keyof TConfig ? Pick<ProviderContext, "stt"> : Record<never, never>) & ("resolver" extends keyof TConfig ? Pick<ProviderContext, "resolver"> : Record<never, never>) & ("choice" extends keyof TConfig ? Pick<ProviderContext, "choice"> : Record<never, never>);
 export interface ProxiedOAuthConfig {
     authorizeUrl: string;
     tokenUrl: string;
@@ -1921,7 +1929,7 @@ export interface OperationContractMetadata {
     lifecycle?: OperationLifecycle;
     deprecation?: OperationDeprecationMetadata;
 }
-export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOutput extends SchemaLike = SchemaLike> {
+export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOutput extends SchemaLike = SchemaLike, TContext = ProviderContext> {
     /**
      * Short English display title for the operation. The SDK passes it through
      * verbatim; the APIFuse registry derives the operation's en locale title
@@ -1951,7 +1959,7 @@ export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOu
     retryOnAuthRefresh?: boolean;
     input: TInput;
     output: TOutput;
-    handler(ctx: ProviderContext, input: InferSchemaOutput<TInput>): OperationHandlerResult<InferSchemaOutput<TOutput>> | Promise<OperationHandlerResult<InferSchemaOutput<TOutput>>>;
+    handler(ctx: TContext, input: InferSchemaOutput<TInput>): OperationHandlerResult<InferSchemaOutput<TOutput>> | Promise<OperationHandlerResult<InferSchemaOutput<TOutput>>>;
     fixtures?: {
         request: InferSchemaOutput<TInput>;
         response: InferSchemaOutput<TOutput>;

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.36",
+	"version": "2.2.0-beta.37",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/cli/templates/provider/index.ts.tpl

@@ -1,9 +1,9 @@
-import { defineProvider } from "@apifuse/provider-sdk/provider";
+import { defineProvider, type ProviderContextOf } from "@apifuse/provider-sdk/provider";
 
 import { providerMeta } from "./meta";
 import { operations } from "./operations";
 
-export default defineProvider({
+const buildProvider = defineProvider({
   id: "{{PROVIDER_ID}}",
   version: "1.0.0",
   runtime: "{{RUNTIME}}"{{BROWSER_BLOCK}},
@@ -11,5 +11,8 @@ export default defineProvider({
   reviewed: "community",
   {{SECRETS_BLOCK}}{{CREDENTIAL_BLOCK}}auth: {{AUTH_BLOCK}},
   meta: providerMeta,
-  operations: operations,
 });
+
+export type ProviderContext = ProviderContextOf<typeof buildProvider>;
+
+export default buildProvider({ operations });

package/src/cli/templates/provider/operations/ping.ts.tpl

@@ -1,8 +1,9 @@
 import { defineOperation } from "@apifuse/provider-sdk/provider";
+import type { ProviderContext } from "../index";
 
 import { pingInputSchema, pingOutputSchema } from "../schemas/ping";
 
-export const pingOperation = defineOperation({
+export const pingOperation = defineOperation<ProviderContext>()({
   descriptionKey: "operations.ping.description",
   input: pingInputSchema,
   output: pingOutputSchema,