@apifuse/provider-sdk 2.2.0-beta.22 → 2.2.0-beta.24

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/runtime/stt.ts

@@ -14,6 +14,7 @@ import type {
 	VerificationCodeCandidateSource,
 	VerificationCodeExtractionResult,
 } from "../types.js";
+import { createTimeoutController, isTimeoutLikeError } from "./timeout.js";
 
 export const APIFUSE__STT__BACKEND_ENV = "APIFUSE__STT__BACKEND";
 export const APIFUSE__STT__MODEL_ENV = "APIFUSE__STT__MODEL";
@@ -169,15 +170,6 @@ function normalizeCloudflareLanguage(language: Bcp47Locale | undefined): string
 	return language?.split("-")[0]?.toLowerCase();
 }
 
-function isTimeoutLikeError(error: unknown): error is Error {
-	return (
-		error instanceof Error &&
-		(error.name === "AbortError" ||
-			error.name === "TimeoutError" ||
-			/\b(timed out|timeout|deadline exceeded)\b/i.test(error.message))
-	);
-}
-
 function toSttTransportError(error: unknown): TransportError {
 	if (error instanceof TransportError) return error;
 	if (isTimeoutLikeError(error)) {
@@ -194,16 +186,6 @@ function toSttTransportError(error: unknown): TransportError {
 	});
 }
 
-function createTimeoutController(signalTimeoutMs: number): {
-	controller: AbortController;
-	clear: () => void;
-} {
-	const controller = new AbortController();
-	const timeout = setTimeout(() => controller.abort(), signalTimeoutMs);
-	timeout.unref?.();
-	return { controller, clear: () => clearTimeout(timeout) };
-}
-
 function toCloudflareInput(request: SttTranscribeRequest): Record<string, unknown> {
 	const prompt = resolveSttPrompt(request);
 	const input: Record<string, unknown> = {

package/src/runtime/timeout.ts

@@ -0,0 +1,18 @@
+export function isTimeoutLikeError(error: unknown): error is Error {
+	return (
+		error instanceof Error &&
+		(error.name === "AbortError" ||
+			error.name === "TimeoutError" ||
+			/\b(timed out|timeout|deadline exceeded)\b/i.test(error.message))
+	);
+}
+
+export function createTimeoutController(signalTimeoutMs: number): {
+	controller: AbortController;
+	clear: () => void;
+} {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), signalTimeoutMs);
+	timeout.unref?.();
+	return { controller, clear: () => clearTimeout(timeout) };
+}

package/src/server/serve.ts

@@ -48,12 +48,14 @@ import {
 	createNativeNetworkClient,
 } from "../runtime/native-network.js";
 import { getProviderBaseUrl } from "../runtime/provider.js";
+import { createOcrClientFromEnv } from "../runtime/ocr.js";
 import {
 	PROXY_AUTH_IP_DENIED_CODE,
 	PROXY_EDGE_AUTH_REJECTED_CODE,
 	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,
@@ -92,12 +94,14 @@ import type {
 	OperationErrorCode,
 	OperationHttpStreamTransport,
 	OperationSseTransport,
+	OcrContext,
 	ProviderErrorStatus,
 	ProviderContext,
 	ProviderDefinition,
 	ProviderProxyPolicy,
 	ProviderRuntimeState,
 	ProviderStreamEvent,
+	ResolverContext,
 	StealthClient,
 	SttContext,
 } from "../types.js";
@@ -298,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;
 }
@@ -316,6 +332,7 @@ function createProviderContext(
 	options: ProviderServerOptions = {},
 	state: ProviderRuntimeState = createUnsupportedProviderRuntimeState(),
 	proxyTelemetry?: ProxyTelemetryCollector,
+	signal?: AbortSignal,
 ): ProviderContext {
 	const baseUrl = getProviderBaseUrl(provider);
 	const stealthBaseUrl = getProviderStealthBaseUrl(provider);
@@ -325,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,
@@ -346,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,
@@ -357,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)
@@ -389,13 +413,23 @@ function createProviderContext(
 			: {}),
 		trace: createTraceContext(),
 		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;
@@ -464,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,
@@ -476,6 +515,7 @@ function createAuthFlowContext(
 				values: request.connection.secrets,
 			})
 		: undefined;
+	const cache = createProviderCache({ providerId: provider.id });
 
 	return {
 		context: {
@@ -512,7 +552,17 @@ function createAuthFlowContext(
 			]),
 			credential,
 			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,
@@ -596,6 +646,10 @@ export type ProviderServerOptions = {
 	};
 	/** Optional STT override for tests or custom hosts; local/prod normally resolves from env. */
 	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. */
@@ -1511,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;
@@ -1551,6 +1614,7 @@ async function handleOperation(
 					operationId,
 					ctx,
 					request,
+					signal,
 				})
 			: await executeOperation(provider, operationId, ctx, request.input);
 		if (streaming && operation) {
@@ -1937,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);
 			}
@@ -2005,6 +2077,7 @@ export function createServerApp(
 				options,
 				state,
 				proxyTelemetry,
+				c.req.raw.signal,
 			);
 			if (response instanceof Response) {
 				logProviderSuccess(
@@ -2381,7 +2454,9 @@ export async function serve(
 
 	const app = createServerApp(provider, {
 		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

@@ -3,6 +3,7 @@ import { describe, expect, it } from "bun:test";
 import { createProviderCache } from "../runtime/cache.js";
 import { createTestProviderChoiceContext } from "../runtime/choice.js";
 import { createMemoryProviderRuntimeState } from "../runtime/state.js";
+import { createUnsupportedOcrClient } from "../runtime/ocr.js";
 import { createUnsupportedSttClient } from "../runtime/stt.js";
 import {
 	createNativeEgressAuthorization,
@@ -395,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 });
 			},
@@ -559,9 +562,15 @@ function createUpstreamContext(
 			: {}),
 		trace: { span: async (_name, fn) => fn() },
 		auth: { requestField: async (name) => unsupported(`ctx.auth.requestField(${name})`) },
+		ocr: createUnsupportedOcrClient(
+			"Standard test upstream context does not support ctx.ocr.recognize",
+		),
 		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,
@@ -684,9 +693,15 @@ export function createSnapshotContext(rawFixture: unknown): ProviderContext {
 		auth: {
 			requestField: async (name) => unsupported(`ctx.auth.requestField(${name})`),
 		},
+		ocr: createUnsupportedOcrClient(
+			"Standard test snapshot context does not support ctx.ocr.recognize",
+		),
 		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

@@ -243,6 +243,61 @@ export interface SmsOtpMatcherDefinition {
 	extractOtp(body: string): string | null;
 }
 
+export interface ProviderOcrConfig {
+	readonly mode: "required" | "optional";
+}
+
+export type OcrImageInput =
+	| { readonly kind: "base64"; readonly data: string; readonly mediaType?: string }
+	| { readonly kind: "url"; readonly url: string };
+
+export interface OcrRecognizeRequest {
+	readonly image: OcrImageInput;
+	readonly hint?: "captcha" | "document" | "generic";
+	readonly prompt?: string;
+	readonly maxTokens?: number;
+	readonly timeoutMs?: number;
+}
+
+export interface OcrWarning {
+	readonly code: string;
+	readonly message: string;
+}
+
+export interface OcrResult {
+	readonly text: string;
+	readonly model: string;
+	readonly warnings?: readonly OcrWarning[];
+}
+
+export interface OcrCaptchaOptions {
+	readonly length?: number;
+	/** Allowed characters. A RegExp is applied to each character, not to the whole text. */
+	readonly charset?: string | RegExp;
+	readonly caseSensitive?: boolean;
+	readonly maxCandidates?: number;
+}
+
+export interface OcrCaptchaCandidate {
+	readonly text: string;
+	readonly satisfiesConstraints: boolean;
+}
+
+export interface OcrCaptchaResult {
+	readonly text: string;
+	readonly candidates: readonly OcrCaptchaCandidate[];
+	readonly satisfiesConstraints: boolean;
+	readonly model: string;
+}
+
+export interface OcrContext {
+	recognize(request: OcrRecognizeRequest): Promise<OcrResult>;
+	extractCaptchaText(
+		image: OcrImageInput,
+		options?: OcrCaptchaOptions,
+	): Promise<OcrCaptchaResult>;
+}
+
 export type SttTranscribeMode = "general" | "otp";
 export type SttPromptPolicy = "none" | "default-hint" | "custom-hint";
 export type SttUnsupportedOptionPolicy = "warn" | "error";
@@ -252,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;
@@ -330,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. */
@@ -794,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";
 
@@ -1563,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 = {
@@ -1604,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;
@@ -1889,7 +2055,9 @@ export interface FlowContext {
 	env: EnvContext;
 	credential?: CredentialContext;
 	context: ContextScratchpad;
+	ocr: OcrContext;
 	stt: SttContext;
+	resolver: ResolverContext;
 	auth: AuthFlowTerminalContext;
 }
 
@@ -1932,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. */
@@ -1993,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,
@@ -2014,7 +2194,9 @@ export interface ProviderContext {
 	browser: BrowserClient;
 	trace: TraceContext;
 	auth: AuthContext;
+	ocr: OcrContext;
 	stt: SttContext;
+	resolver: ResolverContext;
 	choice: ProviderChoiceContext;
 }
 
@@ -2187,7 +2369,9 @@ export interface ProviderDefinition {
 		platform: StealthPlatform;
 	};
 	proxy?: ProviderProxyConfig;
+	ocr?: ProviderOcrConfig;
 	stt?: ProviderSttConfig;
+	resolver?: ProviderResolverConfig;
 	browser?: {
 		engine: BrowserEngine;
 	};