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

package/src/runtime/stealth.ts

@@ -787,7 +787,6 @@ function createSessionFetcher(
 		const resolvedProxy = await resolveProxyConfigAsync({
 			proxy: options?.proxy ?? clientOptions.proxy,
 			upstream: clientOptions.upstream,
-			apifuseConfig: clientOptions.apifuseConfig,
 			affinityKey: clientOptions.affinityKey,
 			proxyAttempt: computeProxyAttemptIndex({
 				baseProxyAttempt: clientOptions.proxyAttempt,
@@ -860,11 +859,9 @@ function createSessionFetcher(
 			// A registry vendor chain (smartproxy/nodemaven) is the only policy whose
 			// successive attempts resolve a *different* endpoint, so it is the only one
 			// that may widen the attempt cap to the pool span, de-duplicate endpoints,
-			// and drive allocator stale-pool refresh. A static custom/decodo policy
-			// resolves the same URL every attempt: widening/refreshing it would resend
-			// the request dozens of times (up to maxAttempts × refreshes) and bypass
-			// retry:false and unsafe-method controls. Static policies therefore follow
-			// the ordinary transport-retry budget instead.
+			// and drive allocator stale-pool refresh. Deprecated custom/decodo policies
+			// have no managed endpoint to rotate or refresh, so they follow the ordinary
+			// transport-retry budget instead.
 			const rotatesRegistryChain =
 				usesPolicyAllocator && policyResolvesRegistryVendorChain(policyProxy);
 			const maxAttempts = rotatesRegistryChain ? policyProxyAttemptCap : retryAttemptCap;

package/src/server/serve.ts

@@ -55,6 +55,7 @@ import {
 	PROXY_POOL_EXHAUSTED_CODE,
 } from "../runtime/proxy-errors.js";
 import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector } from "../runtime/proxy-telemetry.js";
+import { bindResolverSignal, createResolverClientFromEnv } from "../runtime/resolver.js";
 import {
 	assertRequiredSecretsPresent,
 	listMissingRequiredSecrets,
@@ -100,6 +101,7 @@ import type {
 	ProviderProxyPolicy,
 	ProviderRuntimeState,
 	ProviderStreamEvent,
+	ResolverContext,
 	StealthClient,
 	SttContext,
 } from "../types.js";
@@ -300,6 +302,18 @@ export function resolveProviderProxyAffinityKey(
 	return connectionKey ?? provider.id;
 }
 
+export function resolveProviderResolverIdentityScope(
+	provider: ProviderDefinition,
+	affinityKey: string,
+	contextId: string,
+): string {
+	return JSON.stringify({
+		proxy: provider.proxy ?? null,
+		affinityKey,
+		contextId,
+	});
+}
+
 function resolveOperationConnectionId(request: OperationRequest): string | undefined {
 	return request.connection?.id ?? request.connectionId;
 }
@@ -318,6 +332,7 @@ function createProviderContext(
 	options: ProviderServerOptions = {},
 	state: ProviderRuntimeState = createUnsupportedProviderRuntimeState(),
 	proxyTelemetry?: ProxyTelemetryCollector,
+	signal?: AbortSignal,
 ): ProviderContext {
 	const baseUrl = getProviderBaseUrl(provider);
 	const stealthBaseUrl = getProviderStealthBaseUrl(provider);
@@ -327,6 +342,11 @@ function createProviderContext(
 		affinityKey: resolveProviderProxyAffinityKey(provider, request, operationId),
 		telemetry: proxyTelemetry,
 	};
+	const resolverIdentityScope = resolveProviderResolverIdentityScope(
+		provider,
+		proxyClientOptions.affinityKey,
+		request.requestId,
+	);
 	let wrappedContext: ProviderContext | undefined;
 	const stealthClientOptions = {
 		upstream: proxyClientOptions.upstream,
@@ -348,6 +368,8 @@ function createProviderContext(
 		connectionId: resolveOperationConnectionId(request),
 		headers: request.headers ?? {},
 	};
+	const requestState = state.forConnection(requestContext.connectionId);
+	const cache = createProviderCache({ providerId: provider.id });
 	const context = wrapWithInstrumentation({
 		env,
 		credential,
@@ -359,8 +381,8 @@ function createProviderContext(
 				retryResponseMeta.set(wrappedContext, summary);
 			},
 		}),
-		cache: createProviderCache({ providerId: provider.id }),
-		state,
+		cache,
+		state: requestState,
 		stealth: stealthBaseUrl
 			? stealthProfile
 				? createStealthClient(stealthBaseUrl, stealthProfile.name, stealthClientOptions)
@@ -393,12 +415,21 @@ function createProviderContext(
 		auth: createAuthStub(),
 		ocr: options.ocr ?? createOcrClientFromEnv(provider.ocr),
 		stt: options.stt ?? createSttClientFromEnv(provider.stt),
+		resolver: bindResolverSignal(
+			options.resolver ??
+				createResolverClientFromEnv(provider.resolver, undefined, {
+					allowedHosts: provider.allowedHosts,
+					cache,
+					identityScope: resolverIdentityScope,
+				}),
+			signal,
+		),
 		choice: createProviderChoiceContext({
 			providerId: provider.id,
 			env,
 			request: requestContext,
 			credential,
-			state,
+			state: requestState,
 		}),
 	});
 	wrappedContext = context;
@@ -467,6 +498,11 @@ function createAuthFlowContext(
 			request.providerId ??
 			provider.id,
 	};
+	const resolverIdentityScope = resolveProviderResolverIdentityScope(
+		provider,
+		proxyClientOptions.affinityKey,
+		request.requestId,
+	);
 	const stealthClientOptions = {
 		upstream: proxyClientOptions.upstream,
 		affinityKey: proxyClientOptions.affinityKey,
@@ -479,6 +515,7 @@ function createAuthFlowContext(
 				values: request.connection.secrets,
 			})
 		: undefined;
+	const cache = createProviderCache({ providerId: provider.id });
 
 	return {
 		context: {
@@ -517,6 +554,15 @@ function createAuthFlowContext(
 			context: flowContextStore.context,
 			ocr: options.ocr ?? createOcrClientFromEnv(provider.ocr),
 			stt: options.stt ?? createSttClientFromEnv(provider.stt),
+			resolver: bindResolverSignal(
+				options.resolver ??
+					createResolverClientFromEnv(provider.resolver, undefined, {
+						allowedHosts: provider.allowedHosts,
+						cache,
+						identityScope: resolverIdentityScope,
+					}),
+				signal,
+			),
 			auth: createAuthFlowHelpers({ signal }),
 		},
 		getPatch: flowContextStore.getPatch,
@@ -602,6 +648,8 @@ export type ProviderServerOptions = {
 	stt?: SttContext;
 	/** Optional OCR override for tests or custom hosts; local/prod normally resolves from env. */
 	ocr?: OcrContext;
+	/** Optional resolver override for tests or custom hosts; local/prod normally resolves from env. */
+	resolver?: ResolverContext;
 	/** Optional runtime state override for tests or custom hosts. Production resolves Redis from env and fails closed when unavailable. */
 	state?: ProviderRuntimeState;
 	/** Allow process-local runtime state only for local development and tests. */
@@ -1517,8 +1565,17 @@ async function handleOperation(
 	options: ProviderServerOptions = {},
 	state: ProviderRuntimeState = createUnsupportedProviderRuntimeState(),
 	proxyTelemetry?: ProxyTelemetryCollector,
+	signal?: AbortSignal,
 ): Promise<Response | OperationResponse> {
-	const ctx = createProviderContext(provider, request, operationId, options, state, proxyTelemetry);
+	const ctx = createProviderContext(
+		provider,
+		request,
+		operationId,
+		options,
+		state,
+		proxyTelemetry,
+		signal,
+	);
 	const operation = provider.operations[operationId];
 	const streaming = operation?.transport?.kind && operation.transport.kind !== "json";
 	let cleanupCalled = false;
@@ -1557,6 +1614,7 @@ async function handleOperation(
 					operationId,
 					ctx,
 					request,
+					signal,
 				})
 			: await executeOperation(provider, operationId, ctx, request.input);
 		if (streaming && operation) {
@@ -1943,7 +2001,15 @@ export function createServerApp(
 			}
 			const request = operationRequestFromForwardingEnvelope(envelope);
 			operationId = envelope.operationId;
-			const ctx = createProviderContext(provider, request, operationId, options, state);
+			const ctx = createProviderContext(
+				provider,
+				request,
+				operationId,
+				options,
+				state,
+				undefined,
+				signal,
+			);
 			if (deadlineAtMs !== undefined && deadlineAtMs <= Date.now()) {
 				throw new StatefulRoutingDeadlineError(envelope.requestId, envelope.deadlineAt as string);
 			}
@@ -2011,6 +2077,7 @@ export function createServerApp(
 				options,
 				state,
 				proxyTelemetry,
+				c.req.raw.signal,
 			);
 			if (response instanceof Response) {
 				logProviderSuccess(
@@ -2389,6 +2456,7 @@ export async function serve(
 		logger: options.logger,
 		ocr: options.ocr,
 		stt: options.stt,
+		resolver: options.resolver,
 		state: options.state,
 		allowMemoryStateFallback: options.allowMemoryStateFallback,
 		operationExecutor: options.operationExecutor,

package/src/testing/run.ts

@@ -396,6 +396,8 @@ function createUpstreamContext(
 				},
 			}),
 			close: async () => {},
+			cookies: async () =>
+				(await browserAction("cookies")).data as Awaited<ReturnType<BrowserPage["cookies"]>>,
 			fill: async (selector, textValue) => {
 				await browserAction("fill", { selector, text: textValue });
 			},
@@ -566,6 +568,9 @@ function createUpstreamContext(
 		stt: createUnsupportedSttClient(
 			"Standard test upstream context does not support ctx.stt.transcribe",
 		),
+		resolver: {
+			solve: async () => unsupported("ctx.resolver.solve"),
+		},
 		choice: createTestProviderChoiceContext({
 			providerId: `standard-test-${operationName}`,
 			request,
@@ -694,6 +699,9 @@ export function createSnapshotContext(rawFixture: unknown): ProviderContext {
 		stt: createUnsupportedSttClient(
 			"Standard test snapshot context does not support ctx.stt.transcribe",
 		),
+		resolver: {
+			solve: async () => unsupported("ctx.resolver.solve"),
+		},
 		choice: createTestProviderChoiceContext({
 			providerId: "standard-test",
 			request,

package/src/types.ts

@@ -307,6 +307,94 @@ 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.
+ *
+ * `2captcha` is the vendor already carrying production traffic in
+ * `apifuse-provider-tabelog`.
+ *
+ * Union order is documentation only; the effective fallback order is whatever
+ * `ProviderResolverConfig.vendors` declares.
+ */
+export type ProviderResolverVendor =
+	| "browser"
+	| "capsolver"
+	| "capmonster"
+	| "2captcha"
+	| "custom";
+
+/**
+ * Token-family kinds resolve to `{ form: "token" }`. Cookie-family kinds resolve
+ * to `{ form: "cookies" }`; network-identity binding is defined per kind. `aws_waf`
+ * was measured portable across residential leases on buyee, while `cf_clearance`
+ * remains unmeasured here and is treated as identity-scoped because it is widely
+ * described as IP-bound.
+ */
+export type ProviderChallenge =
+	| {
+			readonly kind: "turnstile";
+			readonly siteKey: string;
+			readonly pageUrl: string;
+			readonly action?: string;
+			readonly cdata?: string;
+		}
+	| {
+			readonly kind: "recaptcha_v2";
+			readonly siteKey: string;
+			readonly pageUrl: string;
+		}
+	| {
+			readonly kind: "recaptcha_v3";
+			readonly siteKey: string;
+			readonly pageUrl: string;
+			readonly action: string;
+			readonly minScore?: number;
+		}
+	| {
+			readonly kind: "hcaptcha";
+			readonly siteKey: string;
+			readonly pageUrl: string;
+		}
+	| {
+			readonly kind: "cloudflare_interstitial";
+			readonly pageUrl: string;
+			readonly blockedHtml?: string;
+		}
+	| {
+			readonly kind: "aws_waf";
+			readonly pageUrl: string;
+			readonly captchaScript?: string;
+			readonly context?: string;
+			readonly iv?: string;
+		};
+
+export type ProviderChallengeKind = ProviderChallenge["kind"];
+
+/**
+ * Token solutions carry no network-identity binding. Cookie-solution binding is
+ * per challenge kind: `aws_waf` was measured portable across residential leases
+ * on buyee, while `cf_clearance` is unmeasured here and treated as scoped to the
+ * identity that produced it. The provider attaches the returned cookies to its
+ * own requests.
+ */
+export type ChallengeSolution =
+	| { readonly form: "token"; readonly token: string }
+	| {
+			readonly form: "cookies";
+			readonly cookies: Readonly<Record<string, string>>;
+			readonly userAgent: string;
+		};
+
+export interface ProviderResolverConfig {
+	/** Ordered vendor fallback chain, tried first to last. */
+	readonly vendors: readonly ProviderResolverVendor[];
+	/** Challenge kinds this provider is permitted to request. */
+	readonly kinds: readonly ProviderChallengeKind[];
+}
+
 export type SttAudioInput = {
 	kind: "base64";
 	data: string;
@@ -385,6 +473,10 @@ export interface SttContext {
 	): VerificationCodeExtractionResult;
 }
 
+export interface ResolverContext {
+	solve(challenge: ProviderChallenge, signal?: AbortSignal): Promise<ChallengeSolution>;
+}
+
 export interface HealthJourneySchedule {
 	kind: "interval";
 	/** ISO 8601 duration, for example PT8H. */
@@ -849,10 +941,12 @@ export type ProviderProxyMode = "disabled" | "optional" | "required";
  * - `decodo` — **decodo.com**, the *gateway* proxy that was named "Smartproxy"
  *	 (smartproxy.com) before its 2025 rebrand to Decodo. Sticky sessions via
  *	 username params. A different company from `smartproxy` above.
- *	 **@deprecated** — unused; no managed adapter. Use `smartproxy`/`nodemaven`,
- *	 or the `APIFUSE__PROXY__URL` bring-your-own escape hatch.
- * - `custom` — **@deprecated** bring-your-own static proxy URL marker. The
- *	 `APIFUSE__PROXY__URL` env still works without declaring this value.
+ *	 **@deprecated** — unused; no managed adapter. Declare a
+ *	 `ProviderProxyPolicy` using `smartproxy` or `nodemaven` instead; the
+ *	 `smartproxy` allocator requires `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
+ * - `custom` — **@deprecated** static proxy marker with no managed adapter.
+ *	 Use `ProviderProxyPolicy` with `smartproxy`/`nodemaven`; the `smartproxy`
+ *	 allocator requires `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
  */
 export type ProviderProxyProvider = "smartproxy" | "nodemaven" | "decodo" | "custom";
 
@@ -1521,9 +1615,9 @@ export interface NativeProviderConfig {
 
 export interface ProviderCacheKeyOptions {
 	/**
-	 * Additional field names to omit from stable key material. The SDK always
-	 * omits known secret-bearing names such as serviceKey, authorization,
-	 * cookie, token, password, and secret.
+	 * Additional field names whose values are hashed in stable key material. The
+	 * SDK always hashes values under known secret-bearing names such as serviceKey,
+	 * authorization, cookie, token, password, and secret.
 	 */
 	redactFields?: string[];
 }
@@ -1618,6 +1712,18 @@ export interface BrowserFrame {
 	locator(selector: string): BrowserLocator;
 }
 
+export interface BrowserCookie {
+	readonly name: string;
+	readonly value: string;
+	readonly domain: string;
+	readonly path: string;
+	/** Unix seconds. Absent for a session cookie. */
+	readonly expires?: number;
+	readonly httpOnly: boolean;
+	readonly secure: boolean;
+	readonly sameSite?: "Strict" | "Lax" | "None";
+}
+
 export type BrowserResourceMethod = "GET" | "HEAD";
 
 export type BrowserResourceRequest = {
@@ -1659,6 +1765,11 @@ export type BrowserResourcePolicy = {
 
 export interface BrowserPage extends BrowserFrame {
 	close(): Promise<void>;
+	/**
+	 * Reads the browser context's cookie jar, including httpOnly cookies.
+	 * Cookie expiry values are Unix seconds and are absent for session cookies.
+	 */
+	cookies(): Promise<readonly BrowserCookie[]>;
 	fill(selector: string, text: string): Promise<void>;
 	goto(url: string): Promise<void>;
 	pageId?: string;
@@ -1946,6 +2057,7 @@ export interface FlowContext {
 	context: ContextScratchpad;
 	ocr: OcrContext;
 	stt: SttContext;
+	resolver: ResolverContext;
 	auth: AuthFlowTerminalContext;
 }
 
@@ -1988,7 +2100,14 @@ export type ProviderStateDurationString =
 	| `${number}${"ms" | "s" | "m" | "h" | "d"}`
 	| `PT${string}`;
 
+export type StateNamespaceScope = "connection" | "provider";
+
 export interface StateNamespaceOptions {
+	/**
+	 * State isolation boundary. Connection scope is the default; provider scope
+	 * must be selected explicitly for provider-wide coordination state.
+	 */
+	scope?: StateNamespaceScope;
 	/** Default TTL used when a write omits ttl. Required to avoid unbounded state. */
 	defaultTtl: ProviderStateDurationString;
 	/** Maximum allowed TTL; writes are rejected when they exceed this policy. */
@@ -2049,6 +2168,11 @@ export interface ProviderStateNamespace {
 }
 
 export interface ProviderRuntimeState {
+	/**
+	 * Returns an immutable view bound to one request connection. An unresolved
+	 * connection uses an isolated reserved sentinel, never the provider-global scope.
+	 */
+	forConnection(connectionId: string | undefined): ProviderRuntimeState;
 	namespace(
 		name: string,
 		options: StateNamespaceOptions,
@@ -2072,6 +2196,7 @@ export interface ProviderContext {
 	auth: AuthContext;
 	ocr: OcrContext;
 	stt: SttContext;
+	resolver: ResolverContext;
 	choice: ProviderChoiceContext;
 }
 
@@ -2246,6 +2371,7 @@ export interface ProviderDefinition {
 	proxy?: ProviderProxyConfig;
 	ocr?: ProviderOcrConfig;
 	stt?: ProviderSttConfig;
+	resolver?: ProviderResolverConfig;
 	browser?: {
 		engine: BrowserEngine;
 	};